[MC-APDSU]:
Atom Publishing Protocol:
Data Services URI and Payload Extensions

Intellectual Property Rights Notice for Open Specifications Documentation

§  Technical Documentation. Microsoft publishes Open Specifications documentation for protocols, file formats, languages, standards as well as overviews of the interaction among each of these technologies.

§  Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you may make copies of it in order to develop implementations of the technologies described in the Open Specifications and may distribute portions of it in your implementations using these technologies or your documentation as necessary to properly document the implementation. You may also distribute in your implementation, with or without modification, any schema, IDL’s, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications.

§  No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.

§  Patents. Microsoft has patents that may cover your implementations of the technologies described in the Open Specifications. Neither this notice nor Microsoft's delivery of the documentation grants any licenses under those or any other Microsoft patents. However, a given Open Specification may be covered by Microsoft's Open Specification Promise (available here:  http://www.microsoft.com/interop/osp) or the Community Promise (available here: http://www.microsoft.com/interop/cp/default.mspx). If you would prefer a written license, or if the technologies described in the Open Specifications are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting iplg@microsoft.com.

§  Trademarks. The names of companies and products contained in this documentation may be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights.

§  Fictitious Names. The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in this documentation are fictitious.  No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.

Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than specifically described above, whether by implication, estoppel, or otherwise.

Tools. The Open Specifications do not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments you are free to take advantage of them. Certain Open Specifications are intended for use in conjunction with publicly available standard specifications and network programming art, and assumes that the reader either is familiar with the aforementioned material or has immediate access to it.

Revision Summary

Contents

1   Introduction

1.1   Glossary

1.2   References

1.2.1   Normative References

1.2.2   Informative References

1.3   Protocol Overview (Synopsis

1.4   Relationship to Other Protocols

1.5   Prerequisites/Preconditions

1.6   Applicability Statement

1.7   Versioning and Capability Negotiation

1.7.1   Version 2.0 Summary

1.8   Vendor-Extensible Fields

1.9   Standards Assignments

2   Messages

2.1   Transport

2.2   Message Syntax

2.2.1   Abstract Data Model

2.2.2   Abstract Type System

2.2.3   URI Format: Resource Addressing Rules

2.2.3.1   URI Syntax

2.2.3.2   Service Root (serviceRoot) and Path Prefix (pathPrefix)

2.2.3.3   Resource Path (resourcePath)

2.2.3.4   Resource Path: Construction Rules

2.2.3.5   Resource Path: Semantics

2.2.3.6   Query Options

2.2.3.6.1   System Query Options

2.2.3.6.1.1   Common Expression Syntax

2.2.3.6.1.1.1   Expression Construction and Evaluation Rules

2.2.3.6.1.1.2   Operator Precedence

2.2.3.6.1.1.3   Unary numeric promotions

2.2.3.6.1.1.4   Binary numeric promotions

2.2.3.6.1.1.5   Lifted operators

2.2.3.6.1.1.6   Numeric promotions for method call parameters

2.2.3.6.1.2   Evaluating System Query Options

2.2.3.6.1.3   Expand System Query Option ($expand)

2.2.3.6.1.4   Filter System Query Option ($filter)

2.2.3.6.1.5   Format System Query Option ($format)

2.2.3.6.1.6   OrderBy System Query Option ($orderby)

2.2.3.6.1.7   Skip System Query Option ($skip)

2.2.3.6.1.8   Top System Query Option ($top)

2.2.3.6.1.9   Skip Token System Query Option ($skiptoken)

2.2.3.6.1.10   Inlinecount System Query Option ($inlinecount)

2.2.3.6.1.11   Select System Query Option ($select)

2.2.3.6.2   Custom Query Options

2.2.3.6.3   Service Operation Parameters

2.2.3.7   Data Service Metadata

2.2.3.7.1   Service Document

2.2.3.7.2   Conceptual Schema Definition Language Document for Data Services

2.2.3.7.2.1   Conceptual Schema Definition Language Document for Version 2.0 Data Services

2.2.3.8   URI Equivalence

2.2.3.9   Canonical URIs

2.2.4   HTTP Methods

2.2.4.1   MERGE

2.2.5   HTTP Header Fields

2.2.5.1   Accept

2.2.5.1.1   application/atom+xml

2.2.5.1.2   application/json

2.2.5.2   Content-Type

2.2.5.3   DataServiceVersion

2.2.5.4   ETag

2.2.5.5   If-Match

2.2.5.6   If-None-Match

2.2.5.7   MaxDataServiceVersion

2.2.5.8   X-HTTP-Method

2.2.6   Common Payload Syntax

2.2.6.1   Common Serialization Rules for XML-based Formats

2.2.6.2   AtomPub Format

2.2.6.2.1   Entity Set (as an Atom Feed Element

2.2.6.2.1.1   Inlinecount Representation (for collections of entities

2.2.6.2.2   Entity Type (as an Atom Entry Element)

2.2.6.2.2.1   Entity Type (as an Atom Entry Element) with a Customizable Feed Property Mapping

2.2.6.2.3   Complex Type

2.2.6.2.4   Navigation Property

2.2.6.2.5   EDMSimpleType Property

2.2.6.2.6   Deferred Content

2.2.6.2.6.1   Inline Representation

2.2.6.2.7   Service Document

2.2.6.2.8   Additional Representations

2.2.6.3   JavaScript Object Notation (JSON) Format

2.2.6.3.1   Common JSON Serialization Rules for All EDM Constructs

2.2.6.3.2   Entity Set (as a JSON array)

2.2.6.3.2.1   Inlinecount Representation (for collections of entities)

2.2.6.3.3   Entity Type (as a JSON object)

2.2.6.3.4   Complex Type

2.2.6.3.5   Collection of Complex Type Instances

2.2.6.3.6   Navigation Property

2.2.6.3.7   Collection of EDMSimpleType Values

2.2.6.3.8   EDMSimpleType Property

2.2.6.3.9   Deferred Content

2.2.6.3.9.1   Inline Representation

2.2.6.3.10   Links

2.2.6.3.11   Inlinecount Representation (collections of Links)

2.2.6.3.12   Service Document

2.2.6.4   Raw Format

2.2.6.4.1   EDMSimpleType Property

2.2.6.5   XML Format

2.2.6.5.1   Complex Type

2.2.6.5.2   Collection of Complex Type Instances

2.2.6.5.3   EDMSimpleType Property

2.2.6.5.4   Collection of EDMSimpleType Values

2.2.6.5.5   Links

2.2.6.5.5.1   Inlinecount Representation (collections of Links)

2.2.7   Request Types

2.2.7.1   Insert Request Types

2.2.7.1.1   InsertEntity Request

2.2.7.1.1.1   Examples

2.2.7.1.2   InsertLink Request

2.2.7.1.3   InsertMediaResource Request

2.2.7.2   Retrieve Request Types

2.2.7.2.1   RetrieveEntitySet Request

2.2.7.2.2   RetrieveEntity Request

2.2.7.2.3   RetrieveComplexType Request

2.2.7.2.4   RetrievePrimitiveProperty Request

2.2.7.2.5   RetrieveValue Request

2.2.7.2.6   RetrieveServiceMetadata Request

2.2.7.2.7   RetrieveServiceDocument Request

2.2.7.2.8   RetrieveLink Request

2.2.7.2.9   RetrieveCount Request

2.2.7.2.10   Retrieve Request Containing a Customizable Feed Mapping

2.2.7.2.11   RetrieveMediaResource Request

2.2.7.3   Update Request Types

2.2.7.3.1   UpdateEntity Request

2.2.7.3.1.1   Example

2.2.7.3.2   UpdateComplexType Request

2.2.7.3.3   UpdatePrimitiveProperty Request

2.2.7.3.4   UpdateValue Request

2.2.7.3.5   UpdateLink Request

2.2.7.3.6   UpdateMediaResource Request

2.2.7.3.7   Update Request Containing a Customizable Feed Property Mapping

2.2.7.4   Delete Request Types

2.2.7.4.1   DeleteEntity Request

2.2.7.4.2   DeleteLink Request

2.2.7.4.3   DeleteValue Request

2.2.7.5   Invoke Request

2.2.7.6   Batch Request

2.2.7.6.1   Change Set Syntax

2.2.7.6.1.1   Referencing Requests in a Change Set

2.2.7.6.2   Query Operation Syntax

2.2.7.6.3   HTTP Request Restrictions

2.2.7.6.4   Batch Request Syntax

2.2.7.6.5   Example Batch Request

2.2.7.6.6   Batch Responses

2.2.7.6.7   Batch Response Syntax

2.2.7.6.8   Example Batch Response

2.2.7.7   Tunneled Requests

2.2.8   Response Types

2.2.8.1   Error Response

2.2.8.1.1   XML Error Response

2.2.8.1.2   JSON Error Response

3   Protocol Details

3.1   Client Details

3.1.1   Abstract Data Model

3.1.2   Timers

3.1.3   Initialization

3.1.4   Higher-Layer Triggered Events

3.1.4.1   Common Rules for all Requests

3.1.4.2   Request to Insert Resources

3.1.4.2.1   Sending an InsertEntity Request

3.1.4.2.2   Sending an InsertLink Request

3.1.4.3   Request to Retrieve Resources

3.1.4.3.1   Common Rules for Sending Retrieve Requests

3.1.4.4   Request to Update Resources

3.1.4.4.1   Common Rules for Sending Update Requests

3.1.4.5   Request to Delete Resources

3.1.4.5.1   Common Rules for Sending Delete Requests

3.1.4.6   Request to Invoke a Service Operation

3.1.4.7   Request to Send a Batch of Operations

3.1.5   Message Processing Events and Sequencing Rules

3.1.5.1   Common Rules for Receiving Responses from Data Service Requests

3.1.5.2   Responses from Insert Requests

3.1.6   Other Local Events

3.2   Server Details

3.2.1   Abstract Data Model

3.2.2   Timers

3.2.3   Initialization

3.2.4   Higher-Layer Triggered Events

3.2.5   Message Processing Events and Sequencing Rules

3.2.5.1   Common Rules for Receiving All Data Service Requests

3.2.5.2   Common Rules for Executing Received Insert, Update, or Delete Data Service Requests

3.2.5.2.1   Common Rules for Executing Requests Containing a Customizable Feeds Mapped Property

3.2.5.3   Executing a Received Insert Request

3.2.5.3.1   Executing a Received InsertEntity Request

3.2.5.3.2   Executing a Received InsertLink Request

3.2.5.3.3   Executing a Received InsertMediaResource Request

3.2.5.4   Executing a Received Retrieve Request

3.2.5.4.1   Executing a Received RetrieveEntitySet Request

3.2.5.4.2   Executing a Received RetrieveValue Request

3.2.5.4.3   Executing a Received RetrieveCount Request

3.2.5.5   Executing a Received Update Request

3.2.5.5.1   Executing a Received UpdateEntity Request

3.2.5.6   Executing a Received Delete Request

3.2.5.7   Executing a Received Invoke Request

3.2.5.8   Executing a Received Batch Request

3.2.6   Common Response Codes

3.2.7   Other Local Events

4   Protocol Examples

4.1   Insert a New Entity

4.2   Retrieve Resources

4.2.1   Retrieve a Collection of Entities

4.2.1.1   Retrieve a Collection of Entities Using the AtomPub Format

4.2.1.2   Retrieve a Collection of Entities Using the JSON Format

4.2.1.3   Retrieve a Partial Collection of Entities Using the AtomPub Format

4.2.1.4   Retrieve a Partial Collection of Entities Using the JSON Format

4.2.1.5   Retrieve a Collection of Entities with an Inline Count Using AtomPub Format

4.2.1.6   Retrieve a Collection of Entities with an Inline Count Using JSON Format

4.2.2   Retrieve a Single Entity Using the AtomPub Format

4.2.2.1   Retrieve a Single Entity with a Mapped Property Using the AtomPub Format

4.2.3   Retrieve a Single Entity Using the JSON Format

4.2.4   Retrieve a Single Entity and Its Directly Related Entities Using the AtomPub Format

4.2.5   Retrieve a Single Entity and Its Directly Related Entities Using the JSON Format

4.2.6   Retrieve a Data Service's Metadata Document (CSDL)

4.2.7   Retrieve the Count of a Collection of Entities

4.3   Update an Existing Entity

4.3.1   Replace-based Update Using the AtomPub Format

4.3.2   Replace-based Update Using the JSON Format

4.3.3   Merge-based Update Using the AtomPub Format

4.3.4   Merge-based Update Using the JSON Format

4.4   Update the Relationship Between Two Entities

4.4.1   Update a Relationship Using the AtomPub Format

4.4.2   Update a Relationship Using the JSON Format

4.4.3   Delete an Existing Entity

4.5   Batch Requests

4.6   Working with Media Resources (BLOBs)

4.6.1   Insert a new Media Resource

4.6.2   Update a Media Resource

4.6.3   Query an Existing Media Resource

5   Security

5.1   Security Considerations for Implementers

6   Appendix A: Sample Entity Data Model and CSDL Document

7   Appendix B: Product Behavior

8   Change Tracking

9   Index

1   Introduction

The Atom Publishing Protocol (AtomPub), specified in [RFC5023], is an application-level protocol for publishing and editing Web resources.  When Web services expose resources via  AtomPub, a number of details are not covered by the AtomPub specification which, if defined, can enable additional client scenarios. These details include:

§ An addressing scheme by which resources are identified.

§ Schema for the data content of resources.

§ Payload formats and semantics for batch requests.

§ A Model for handling concurrent updates to resources.

§ Alternate representations of resource content.

This document defines versions 1.0 and 2.0 of a set of extensions to the Atom Publishing Protocol (AtomPub) that specify these details.

The extensions defined in this document enable applications to expose data, using common web technologies, as a data service that can be consumed by clients within corporate networks and across the Internet.

Version 2.0 of the extensions defined by this specification to the AtomPub protocol is a superset of version 1.0 and includes incremental additions to version 1.0. The majority of the extensions defined in this document exist in both versions 1.0 and 2.0 of the extensions defined by this specification to the AtomPub protocol. Any constructs or semantics defined in this document that only exist in version 2.0 of the extensions defined by this specification to the AtomPub protocol are explicitly denoted as such.

1.1   Glossary

The following terms are defined in [MS-GLOS]:

binary large object (BLOB)
globally unique identifier (GUID)
URI
XML Namespace

The following terms are defined in [MC-CSDL]:

alias
annotation
association
AssociationSet
cardinality
collection
ComplexType
ConcurrencyMode
conceptual schema definition language (CSDL)
declared property
dynamic property
Entity Data Model (EDM)
EDMSimpleType
EntityContainer
EntityKey
EntitySet
EntityType
facet
FunctionImport
identifier
namespace
NavigationProperty
OpenEntityType
schema

The following terms are specific to this document:

AtomPub Collection: A set of resources that can be retrieved in whole or in part.

Atom Publishing Protocol (AtomPub): An application-level protocol for publishing and editing Web resources, specified in [RFC5023].

bind: An EntityType instance in a data service (described using Entity Data Model constructs) that may be related to one or more other CSDL instances.  These relationships are represented using associations in an Entity Data Model.  The cardinality of a relationship can be determined by inspecting the Entity Data Model that describes the data service.  The act of associating two EntityType instances is known as 'binding' and of disassociating two instances is known as 'unbinding'.  If two EntityType instances are already associated, then they are considered to be 'bound'.

Change Set: A logical group of one or more of the following request types:

§ Insert Request Types (section 2.2.7.1)

§ Update Request Types (section 2.2.7.3)

§ Delete Request Type (section 2.2.7.4)

§ Invoke Request (section 2.2.7.5), which may be created using the HTTP PUT, POST, or HTTP DELETE method

All of the requests within a Change Set must be successfully processed.  If any request in the Change Set fails, then none of the requests within the Change Set should be processed.

create retrieve update delete (CRUD): This term, typically represented using the abbreviation CRUD, is used to denote the four basic functions of persistent storage.  The 'C' stands for create, the 'R' for retrieve, the 'U' for update, and the 'D' for delete.  This term is used to denote these conceptual actions and does not imply the associated meaning in a particular technology area (for example, databases, file systems, and so on) unless explicitly stated.

Customizable Feed: The Customizable Feed property mappings are used to define a mapping from the properties of an EntityType to elements or attributes in any namespace (including the Atom namespace) in an AtomPub document.  When a property is mapped to an element or an attribute of an element, the value for the property is equal to the value of the specified element or attribute in the AtomPub document.

data service: A server-side application that implements the protocol specified in this document for the purpose of enabling clients to publish and edit resources.  The resources exposed by data services are described using the Entity Data Model (EDM), as specified in [MC-CSDL].

default EntityContainer: A single EntityContainer within a CSDL document, as specified in [MC-CSDL].  Entities in the default container may be identified in a data service URI without specifying the container name, as described in URI Format: Resource Addressing Rules (section 2.2.3).

entity: An instance of an EntityType, as specified in [MC-CSDL].

Entity Data Model Extensions (EDMX): The Entity Data Model Extensions, as specified in [MC-EDMX].

Internationalized Resource Identifier (IRI): A resource identifier, which conforms to the rules for Internationalized Resource Identifiers as defined in [RFC3987].

JavaScript Object Notation  (JSON): This term refers to a small set of formatting rules for the portable representation of structured data, as specified in [RFC4627].

Link: A Link is similar to an association, as specified in [MC-CSDL], but describes a unidirectional relationship between EntityTypes instead of a bidirectional one.  A Link can be:

§ A unidirectional relationship (for example, a Link), which occurs when two EntityTypes are related via an association, but only one of the EntityTypes defines a NavigationProperty bound to the association.

§ A reference to one direction of a bidirectional association between two EntityTypes, as specified in [MC-CSDL].

Primitive Property: A property of type EDMSimpleType defined on an EntityType.

property: An EntityType or ComplexType can have one or more properties of the specified EDMSimpleType, or ComplexType.  A property of an EntityType may be a declared property or a dynamic property, as specified in [MC-CSDL].  A property of ComplexType must be a declared property. 

Note  In CSDL [MC-CSDL], dynamic properties are only defined for use with OpenEntityType [MC-CSDL] instances.

Query Operation: A logical construct that must consist of a single Retrieve Request Types (section 2.2.7.2) or an Invoke Request (section 2.2.7.5) which uses the GET HTTP method.

Resource: A network-accessible data object or service identified by an IRI, as defined in [RFC2616].

Resource Path: The path of a data service URI starting immediately after the Service Root and continuing to the end of the URI's path, as described in Resource Path (section 2.2.3.3).

Service Operation: Represents a FunctionImport, as specified in [MC-CSDL], which only accepts input parameters in a data service.

Service Root: A URI that represents the root of a data service, as described in Service Root (section 2.2.3.2).

Unbind: See the definition for "bind".

MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as described in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.

1.2   References

1.2.1   Normative References

We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact dochelp@microsoft.com. We will assist you in finding the relevant information. Please check the archive site, http://msdn2.microsoft.com/en-us/library/E4BD6494-06AD-4aed-9823-445E921C9624, as an additional source.

[ECMA-262] ECMA international, "ECMAScript Language Specification" ECMA-262, December 1999, http://www.ecma-international.org/publications/standards/Ecma-262.htm

[IANA-MMT] Internet Assigned Numbers Authority, "Mime Media Types", March 2007, http://www.iana.org/assignments/media-types/

[IEEE754-2008] Institute of Electrical and Electronics Engineers, "Standard for Binary Floating-Point Arithmetic", IEEE 754-2008, August 2008, http://ieeexplore.ieee.org/xpls/abs_all.jsp?tp=&isnumber=4610934&arnumber=4610935&punumber=4610933

[MC-CSDL] Microsoft Corporation, "Conceptual Schema Definition File Format", February 2009.           

[RFC2045] Freed, N., and Borenstein, N., "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996, http://ietf.org/rfc/rfc2045.txt

[RFC2046] Freed, N., and Borenstein, N., "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996, http://ietf.org/rfc/rfc2046.txt

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, http://www.ietf.org/rfc/rfc2119.txt

[RFC2616] Fielding, R., Gettys, J., Mogul, J., et al., "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999, http://www.ietf.org/rfc/rfc2616.txt

[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and Stewart, L., "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999, http://www.ietf.org/rfc/rfc2617.txt

[RFC3023] Murata, M., St.Laurent, S., and Kohn, D,. "XML Media Types", RFC 3023, January 2001, http://www.ietf.org/rfc/rfc3023.txt

[RFC3548] Josefsson, S., Ed., "The Base16, Base32, and Base64 Data Encodings", RFC 3548, July 2003, http://www.ietf.org/rfc/rfc3548.txt

[RFC3629] Yergeau, F., "UTF-8, A Transformation Format of ISO 10646", STD 63, RFC 3629, November 2003, http://www.ietf.org/rfc/rfc3629.txt

[RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", RFC 3676, February 2004, http://www.ietf.org/rfc/rfc3676.txt

[RFC3986] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005, http://www.ietf.org/rfc/rfc3986.txt

[RFC3987] Duerst, M., and Suignard, M., "Internationalized Resource Identifiers (IRIs)," RFC 3987, January 2005, http://www.ietf.org/rfc/rfc3987.txt

[RFC4287] Nottingham, M., and Sayre, E.R., "The Atom Syndication Format", RFC 4287, December 2005, http://www.ietf.org/rfc/rfc4287.txt

[RFC4627] Crockford, D., "The application/json Media Type for Javascript Object Notation (JSON)", RFC 4627, July 2006, http://www.ietf.org/rfc/rfc4627.txt

[RFC4646] A. Phillips, Ed., and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 4646, September 2006, http://www.ietf.org/rfc/rfc4646.txt

[RFC5023] Gregorio, J. Ed., and de hOra, B., Ed., "The Atom Publishing Protocol", RFC 5023, October 2007, http://www.ietf.org/rfc/rfc5023.txt

[RFC5234] Crocker, D., Ed., and Overell, P., "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008, http://www.ietf.org/rfc/rfc5234.txt

[XML-BASE] World Wide Web Consortium, "XML Base", June 2001, http://www.w3.org/TR/2001/REC-xmlbase-20010627/

[XMLNS] World Wide Web Consortium, "Namespaces in XML 1.0 (Second Edition)", August 2006, http://www.w3.org/TR/REC-xml-names/

[XMLSCHEMA1] Thompson, H.S., Ed., Beech, D., Ed., Maloney, M., Ed., and Mendelsohn, N., Ed., "XML Schema Part 1: Structures", W3C Recommendation, May 2001, http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/

[XMLSCHEMA2/2] Biron, P.V., Ed. and Malhotra, A., Ed., "XML Schema Part 2: Datatypes Second Edition", W3C Recommendation, October 2004, http://www.w3.org/TR/xmlschema-2

1.2.2   Informative References

[MS-GLOS] Microsoft Corporation, "Windows Protocols Master Glossary", March 2007.           

[REST] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", 2000, http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

1.3   Protocol Overview (Synopsis)

The extensions to the Atom Publishing Protocol defined in this document are used for creating Representational State Transfer (REST)-based [REST] data services, which enable resources, identified using Uniform Resource Identifiers (URIs) and defined in an abstract data model, to be published and edited by web clients within corporate networks and across the Internet using simple Hypertext Transfer Protocol (HTTP) messages.

The Atom Publishing Protocol does not define a URI-addressing scheme, a schema for the data content of the resources that the services expose, a format for batching requests, a concurrency policy or mechanism, or alternate data representations. The extensions described in this document define a uniform, HTTP-based interface for data services that address these shortcomings of the Atom Publishing Protocol. By using this interface, high-level, reusable, general-purpose client libraries and components can consume different services without needing to accommodate custom semantics for each.

The extensions defined in this document depend on HTTP [RFC2616] for transfer of all protocol messages and user data and follow or extend the messaging semantics defined in  AtomPub [RFC5023].

In this document, the entity that initiates the HTTP connection and sends HTTP request messages is referred to as the client, and the entity that responds to the HTTP connection request, and sends HTTP response messages is referred to as the server or data service.  For the purposes of this document, the terms "server" and "data service" have the same meaning and are used interchangeably.

The use of Web-based technologies (such as HTTP) make implementations of this document ideal as a mid-tier service technology for applications, such as Asynchronous JavaScript and XML (AJAX) style applications, Rich Interactive Applications (RIA), and other applications that need to operate against data that is stored across Internet trust boundaries.

1.4   Relationship to Other Protocols

This document defines versions 1.0 and 2.0 of extensions to the AtomPub [RFC5023] specification, which in turn relies on HTTP [RFC2616]. Either HTTP version 1.1 or HTTP version 1.0 may be used with these protocol extensions. The extensions use HTTP headers defined in the HTTP specification, but not referenced in the AtomPub specification.

The extensions defined in this document also use message formats defined by other industry standard specifications, such as the Multipurpose Internet Mail Extensions (MIME) format described in [RFC2046] and the JavaScript Object Notation format described in [RFC4627].

Figure 1: MC-APDSU Relationship to Other Protocols

1.5   Prerequisites/Preconditions

The protocol extensions defined in this document do not provide a mechanism for a client to discover the existence and location of arbitrary data services (of the server).  It is a prerequisite that the client obtain a URI to the server before these extensions can be used.

Neither the Atom Publishing Protocol nor the extensions defined in this document define an authentication or authorization scheme.  Implementers of these extensions should review the recommended security prerequisites in Security Considerations for Implementers (section 5.1) of this document and in [RFC5023] section 15.

1.6   Applicability Statement

AtomPub, as specified in [RFC5023], in combination with the extensions defined in this document, is appropriate for use in Web services which need a uniform, flexible, general purpose interface for exposing create retrieve update delete (CRUD) operations on a data model to clients. It is less suited to Web services that are primarily method-oriented or in which data operations are constrained to certain prescribed patterns.

1.7   Versioning and Capability Negotiation

This document covers versioning issues in the following areas:

Supported Transports: This document can be implemented on top of the Atom Publishing Protocol described in Transport (section 2.1).

Protocol Versions: Clients specify the protocol version using the DataServiceVersion (section 2.2.5.3) and MaxDataServiceVersion (section 2.2.5.7) request headers. Servers specify the protocol version using the DataServiceVersion (section 2.2.5.3) response header.

Security and Authentication Methods: This document supports (but does not require) any authentication scheme which can be supported using HTTP request and response headers. An example of such an authentication protocol is HTTP Basic Access Authentication described in [RFC2617].

Localization: This document does not specify any localization-dependent behavior.

Capability Negotiation: The extensions defined in this document enable limited capability negotiation using the DataServiceVersion (section 2.2.5.3) and MaxDataServiceVersion (section 2.2.5.7) version request headers and the DataServiceVersion (section 2.2.5.3) response header. These headers provide a way to version the extensions defined in this document and do not act as a versioning scheme for the Atom Publishing Protocol in general.

On a request from the client to data service, the DataServiceVersion (section 2.2.5.3) and MaxDataServiceVersion (section 2.2.5.7) version headers may be specified.

If present on the request, the DataServiceVersion (section 2.2.5.3) header value states the version of the protocol extensions used by the client to generate the request. If no DataServiceVersion (section 2.2.5.3) header is provided, then the server must assume a value equal to the maximum version number the server supports.

If present on the request, the MaxDataServiceVersion (section 2.2.5.7) header value specifies the maximum version number the client can accept in a response. The client should set this value to the maximum version number of the protocol extensions it is able to interpret. If the header is not present in a request, the server must assume the same version number as that specified by the DataServiceVersion (section 2.2.5.3) header. If a DataServiceVersion (section 2.2.5.3) header is not present, then the server should assume the client can interpret the maximum version number the server can interpret.

When the server receives a request, it must validate that the version number specified in the DataServiceVersion (section 2.2.5.3) header (or derived value if the header is not present) is less than or equal to the maximum version number it supports. If it is not, then the server must return a response with a 4xx response code. The server should also return a description of the error using the error format defined in Error Response (section 2.2.8.1).

In addition, a server must validate that the version number specified in the MaxDataServiceVersion (section 2.2.5.7) header (or derived value if the header is not present) is greater than or equal to the minimum version number the server needs to use to generate the response. If it is not, then the server must return an error response, described in Error Response (section 2.2.8.1).

On a response from the server to the client, the DataServiceVersion (section 2.2.5.3) header should be specified. The value states the version of the protocol extensions the server used to generate the request and that should be used by the client to determine if it can correctly interpret the response (that is, the value is not larger than the value of the MaxDataServiceVersion (section 2.2.5.7) header sent in the associated request). The value of the header should be the lowest version of the protocol the server can use to fulfill the request.

1.7.1   Version 2.0 Summary

As described in section 1.4, this document defines two versions (1.0 and 2.0) of the extensions to the protocol defined by this specification. This section provides a summary of the protocol constructs defined in this document, which apply only to version 2.0. This section is structured by protocol feature. Each protocol feature described includes a list of the sections which include version 2.0-specific content.

Partial Sets of Entities: Servers may respond to RetrieveEntitySet (section 2.2.7.2.1) GET requests with a response body containing a representation of a partial list of the entities identified by the request URI and a link to the next partial list.

§ 2.2.3.6.1 System Query Options

§ 2.2.3.6.1.9 Skip Token System Query Option ($skiptoken)

§ 3.2.5.4.2 Executing a Received RetrieveEntitySet Request

§ 2.2.6.2.1 Entity Set (as an Atom Feed Element)

§ 2.2.6.3.2 Entity Set (as a JSON array)

RetrieveCount Request: The purpose of the RetrieveCount request (section 2.2.7.2.9) is to enable the count of a collection of EntityType instances to be retrieved by the client.

§ 2.2.3.1 URI Syntax

§ 2.2.3.5 Resource Path: Semantics

§ 2.2.3.6.1 System Query Options

§ 2.2.7 Request Types

§ 2.2.7.2.9 RetrieveCount Request

§ 3.1.4.3.1 Common Rules for Sending Retrieve Requests

§ 3.2.5.4.3 Executing a Received RetrieveCount Request

§ 4.2.6 Retrieve the Count of a Collection of Entities

Inlinecount System Query Option: A data service URI with an Inlinecount System Query Option specifies that the response to the request must include the count N of the total number of entities in the EntitySet, identified by the Resource Path section of the URI.

§ 2.2.3.1 URI Syntax

§ 2.2.3.5 Resource Path: Semantics

§ 2.2.3.6.1 System Query Options

§ 2.2.3.6.1.2 Evaluating System Query Options

§ 2.2.3.6.1.10 Inlinecount System Query Option ($inlinecount)

§ 2.2.6.2.1.1 Inlinecount Representation (for collections of entities)

§ 2.2.6.3.2.1 Inlinecount Representation (for collections of entities)

§ 2.2.6.5.5.1 Inlinecount Representation (for collections of links)

§ 2.2.6.3.10 Inlinecount Representation (for collections of links)

§ 3.2.5.4 Executing a Received Retrieve Request

§ 4.2.1.5 Retrieve a Collection of Entities with an Inline Count Using AtomPub Format

§ 4.2.1.6 Retrieve a Collection of Entities with an Inline Count Using JSON Format

Select System Query Option: A data service URI with a $select System Query Option identifies the same set of entities as a URI without a $select query option; however, the presence of a $select query option specifies that a response from the data service should return a subset, as identified by the value of the $select query option, of the properties that would have been returned had the URI not included a $select query option.

§ 2.2.3.1 URI Syntax

§ 2.2.3.6.1 System Query Options

§ 2.2.3.6.1.2 Evaluating System Query Options

§ 2.2.3.6.1.11 Select System Query Option ($select)

Customizable Feeds: The Customizable Feed property mappings can be used to override an Entity Types default AtomPub representation and specify how one or more properties of an Entity Type should be represented within an AtomPub <atom:entry> element.  This feature of the protocol specifies a set of data service metadata document (see section 2.2.3.7.2) annotations, which enable a property of an Entity Type to be mapped to a child element of an <atom:entry> element, or an XML attribute on the <atom:entry> element, or one of its child elements.  When a property is mapped to an element, the value for the property is used as the value of the mapped-to element or attribute.

§ 2.2.3.7.2 Conceptual Schema Definition Language Document for Data Services

§ 2.2.3.7.2.1 Conceptual Schema Definition Language Document for the Data Services v1.5 Metadata Namespace

§ 2.2.6.2.2 Entity Type (as an Atom Entry Element)

§ 2.2.6.2.2.1 Entity Type (as an Atom Entry Element) with a Customizable Feed Property Mapping

§ 2.2.7.1.1 InsertEntity Request

§ 2.2.7.2.10 Retrieve Request Containing a Customizable Feed Mapping

§ 2.2.7.3.1 UpdateEntity Request

§ 2.2.7.3.7 Update Request Containing a Customizable Feed Mapping

§ 3.2.5.2.1 Common Rules for Executing Requests Containing a Customizable Feeds Mapped Property

§ 4.2.2.1 Retrieve a Single Entity with a Mapped Property Using the AtomPub Format

§ 4.2.6 Retrieve a Data Service's Metadata Document (CSDL)

§ 6 Appendix A: Sample Entity Data Model and CSDL Document

New JSON Response Format: The JSON representation for collections has been enhanced to allow for the represention of additional collection-level metadata:

§ 2.2.6.3 Javascript Object Notation (JSON) Format

1.8   Vendor-Extensible Fields

The AtomPub-based messages defined in Messages (section 2) may be extended by adding additional elements or attributes.  Such extensions MUST NOT be in any of the namespaces listed in Common Serialization Rules for XML-based Formats (section 2.2.6.1).

Additional extensibility rules are defined in [RFC5023] section 6.2.

1.9   Standards Assignments

None.

2   Messages

2.1   Transport

The Atom Publishing Protocol (AtomPub) [RFC5023] and the extensions defined in this specification use HTTP, as specified in [RFC2616], as the transport layer. HTTP operations are performed on resources identified by a URI. URI Format: Resource Addressing Rule (section 2.2.3) describes the resource addressing rules defined by this specification which extend the addressing rules used by AtomPub and HTTP.

A TCP port has not been reserved for these extensions. TCP port 80 is commonly used because many HTTP proxy servers forward only HTTP traffic that use port 80.

This specification does not prescribe a mechanism to secure (authenticate, encrypt, etc) AtomPub communications.  For security recommendations which relate to the protocol's transport layer, see [RFC5023] section 15.

2.2   Message Syntax

This section includes the following:

Abstract Data Model (section 2.2.1) specifies the key concepts of the abstract data model which serve as a basis for the protocol extensions defined in this document. The subsequent sections each define mappings from the data model to each of the protocol extensions defined.

Abstract Type System (section 2.2.2) specifies the Abstract Type System used to define the Primitive types (such as String, Boolean, etc.) used by the protocol extensions defined in this document.

URI Format: Resource Addressing Rules in Abstract Type System (section 2.2.2) specifies a set of rules for constructing URIs which identify each of the constructs in the data model, described in Abstract Data Model (section 2.2.1), which are relevant to the protocol extensions defined in this document.

HTTP Header Fields, as described in HTTP Header Fields (section 2.2.5), specifies the syntax for the HTTP headers defined or used by this document.

HTTP Payload Format Syntax in Common Payload Syntax (section 2.2.6) specifies how data described using the abstract data model in Abstract Data Model (section 2.2.1) is mapped to the AtomPub and JSON for use in the payloads of the HTTP Request Types described in Request Types (section 2.2.7).

Request Types (Request Types (section 2.2.7)) specifies the types of requests that are defined by this document and how each request type is mapped to AtomPub request types as well as constructs in the data model in Abstract Data Model (section 2.2.1)

NOTE: All the example URIs and message payloads used in this section as throughout the remainder of this document are based on the sample conceptual schema definition language (CSDL) document in Appendix A: Sample Entity Data Model and CSDL Document (section 6).

2.2.1   Abstract Data Model

This section describes a data modeling vocabulary that a server MUST use to describe the data it exposes. This modeling vocabulary is also used in subsequent sections of this document to describe data as exchanged by this document. The use of this modeling vocabulary does not mandate a particular data persistence format or implementation on the server, as long as the server's interface is consistent with the protocol described in this document.

The protocol extensions defined in this document use the Entity Data Model as their data modeling vocabulary. Data models can be described in Entity Data Model terms using a conceptual schema definition language (CSDL) document [MC-CSDL]. The remainder of this section provides a brief description of the Entity Data Model and defines how EDM constructs are mapped to the resource types defined in the AtomPub specification.

Entity Data Model: The central concepts in the EDM are entities and associations. Entities are instances of EntityTypes (for example, Customer, Employee, etc) which are structured records consisting of named and typed properties and with a key. ComplexTypes are structured types also consisting of a list of properties but with no key, thus can only exist as a property of a containing entity or as a temporary value. An EntityKey is formed from a subset of properties of the EntityType. The EntityKey (for example, CustomerId, OrderId, etc) is a fundamental concept to uniquely identify instances of EntityTypes and allows EntityType instances to participate in relationships. Entities are grouped in EntitySets (for example, Customers is a set of Customer instances). Associations define the relationship between two or more EntityTypes (for example, Employee WorksFor Department).  Instances of associations are grouped in AssociationSets. NavigationProperties are special properties on EntityTypes which are bound to a specific association and can be used to refer to associations through an entity instead of explicitly through an association instance.  Finally, all instance containers (EntitySets and AssociationSets) are grouped in an EntityContainer.

Entity Data Model constructs map to the data model concepts used in the AtomPub specification as shown in the following Entity Data Model Concepts Mapped to AtomPub Resource Types table.  Common Payload Syntax (section 2.2.6) describes how these conceptual AtomPub resources (collection, Entry Resource, etc) are represented using multiple formats in request and response messages used by this document.

Table: Entity Data Model Concepts Mapped to AtomPub Resource Types

2.2.2   Abstract Type System

The Abstract Type System used to define the Primitive types supported by a data service is defined in [MC-CSDL] (section 2.2.1). When the value of a Primitive type needs to be represented in a URI or HTTP header it should use the 'Primitive Type Literal Form' representation defined in the following Literal Form of Entity Data Model Primitive Types table.  Primitive type representations in request and response payloads are defined in format-specific sections of this document.

The Shared ABNF [RFC5234] Grammar Rules for Primitive Types listing that follows the grammar rules in this section makes reference to the following shared ABNF [RFC5234] grammar rules.

Listing: Shared ABNF Grammar Rules for Primitive Types

Table: Literal Form of Entity Data Model Primitive Types

2.2.3   URI Format: Resource Addressing Rules

The Atom Publishing Protocol specifies operations for publishing and editing resources using HTTP, but does not constrain the form of the URIs, as specified in [RFC3986], that are used to identify the resources (see [RFC5023] section 4.1).  This document extends AtomPub by defining a mapping from elements in an Entity Data Model, described using a conceptual schema definition language (CSDL) document, to the resource types defined in section 4.2 of [RFC5023].  See Abstract Data Model (section 2.2.1) for a mapping of EDM constructs to AtomPub resources.

As specified in [RFC5023] (section 4.1), the Atom Publishing Protocol [RFC5023] specifies the formats of the representations that are exchanged and the actions that can be performed on the Internationalized Resource Identifiers (IRI) embedded in those representations; it does not constrain the form of the URIs that are used. Following that paradigm, this section (and its subsections) defines a set of recommended (but not required) rules for constructing a URI or IRI to identify the various parts of the data and metadata in an Entity Data Model.

Servers and clients MAY use alternate URI path construction rules as HTTP [RFC2616] specifies that the URI space of each server is controlled by that server. The extensions defined in this specification impose no further constraints on that control when constructing the authority and path segments of a URI. However, servers conforming to this specification MUST honor the rules for query string construction as defined in this section and its subsections.

Server authors are encouraged to follow the URI path construction rules (in addition to the required query string rules) defined in this specification when possible, as such consistency promotes an ecosystem of reusable client components and libraries.

Before an IRI can be used by an HTTP request, the IRI is first converted to a URI according to the algorithm defined in [RFC3987] section 3.1.  For the remainder of this document, the term URI is used to refer to a URI or an IRI which has been converted to a URI.

2.2.3.1   URI Syntax

The Augmented BNF for URI Construction listing that follows in this section specifies that a data service URI (see dataSvcAbs-URI) is comprised of four sections: the scheme [RFC3986], a data Service Root or Path Prefix, a Resource Path, and Query Options, which, when composed, form an absolute URI to address any EntitySet, EntityType instance, property, or ComplexType in an Entity Data Model.

Servers that conform to this specification MAY follow the grammar below when constructing the scheme, Service Root, and Resource Path URI components of a data service URI. All servers MUST follow the grammar rules shown when constructing and parsing the Query Options section of a data service URI.

Listing: Augmented BNF for URI Construction

2.2.3.2   Service Root (serviceRoot) and Path Prefix (pathPrefix)

The serviceRoot section of a data service URI represents the location of the root of a data service.  The resource identified by this URI MUST be an AtomPub Service Document, as specified in [RFC5023] (or an alternate representation of Atom Service Document data if a different format is requested), which enumerates all of the collections of resources available for the data service.

Example valid URIs (as defined by the grammar in section 2.2.3.1), including only the URI scheme (http:// in the examples below) and serviceRoot elements are:

http://host

http://::1:8080

http://api.constoso.com/v1/dataservice

This pathPrefix section of a data service URI is a data service defined sequence of URI path segments. This specification applies no further requirements to a pathPrefix.

Subsequent examples in this document use a URI scheme of http://.  This is done to show a complete example. However, the URI-addressing rules defined in this document do not mandate the http:// scheme be used to address elements on an Entity Data Model.

2.2.3.3   Resource Path (resourcePath)

This section describes the construction rules for the resource path part of a data service URI. These rules dictate how the names of EntitySets, EntityTypes, entity NavigationProperties, Members, and Service Operations may be composed to generate a URI that identifies a resource exposed by a data service.

Using the example Entity Data Model in Appendix A: Sample Entity Data Model and CSDL Document (section 6), example URIs including the scheme, serviceRoot, and resourcePath elements are:

Resource Path: Semantics (section 2.2.3.5) describes the meaning of the various resource paths which can be constructed using the rules noted in the Augmented BNF for URI Construction listing in URI Syntax (section 2.2.3.1).  In addition, this section notes additional constraints specific to particular elements of the resource path.

2.2.3.4   Resource Path: Construction Rules

This section further defines grammar rules noted in the Augmented BNF for URI Construction listing in URI Syntax (section 2.2.3.1) which map directly to constructs defined in an Entity Data Model (EDM).

entityContainer: The name of an EntityContainer in the EDM model associated with the data service.

entitySet: The name of an EntitySet in the EDM model associated with the data service. EntitySet names MAY<1> be directly followed by open and close parenthesis (for example, Customers() ). However, not appending the parenthesis is also valid and considered the canonical form of an EntitySet name.

If an EntitySet is not in the default Entity Container, then the URI MUST qualify the EntitySet name with the EntityContainer name as follows:

entityType: The name of an EntityType in the EDM model associated with the data service. The EntityType identified MAY be an OpenEntityType.

entityProperty: The name of a declared property or dynamic property, of type EDMSimpleType on an EntityType or a declared property of type EDMSimpleType defined on a ComplexType in the EDM model associated with the data service.

If the prior URI path segment identifies an EntityType instance in EntitySet ES1, this value MUST be the name of a declared property or dynamic property, of type EDMSimpleType, on the base EntityType of set ES1.

If the prior URI path segment represents an instance of ComplexType CT1, this value MUST be the name of a declared property defined on ComplexType CT1.

entityComplexProperty: The name of a declared property, of type ComplexType, on an EntityType in the EDM model associated with the data service.

If the prior URI path segment identifies an instance of an EntityType ET1, this value MUST be the name of a declared property or dynamic property on type ET1 which represents a ComplexType instance.

If the prior URI path segment identifies an instance of a ComplexType CT1, this value MUST be the name of a declared property on CT1 which represents a ComplexType instance.

entityNavProperty: Identifies the name of a NavigationProperty on an EntityType.

If the prior URI path segment identifies an instance of an EntityType ET1, this value MUST be the name of a NavigationProperty on type ET1.

If the URI path segment preceding an entityNavProperty segment is "$links", then there MUST NOT be any subsequent path segments in the URI after the entityNavProperty.  If additional segments exist, the URI MUST be treated as invalid.  For example, there MUST NOT exist a path segment after the Orders segment in the URI:

entityNavProperty-es: This rule is the same as entityNavProperty, but with the added constraint that the NavigationProperty MUST point to an endpoint of an association with a cardinality of "many" (for example, such that traversing the association yields a set).

entityNavProperty-et: This rule is the same as entityNavProperty, but with the added constraint that the NavigationProperty MUST identify an EntityType instance.

keyPredicate: Identifies an EntityKey.

keyPredicate-single: Identifies the EntityKey value of an EntityType whose EntityKey is comprised of only one Property.

The Entity Data Model defines that each such key value must be non-nullable, immutable, and be an EDMSimpleType.  The representation of an EDMSimpleType value in a data service URI MUST follow the syntax rules defined in Abstract Type System (section 2.2.2).

An EntityKey consisting of a single EntityType property MAY<2> be represented using the "<Entity Type property name> = <Entity Type property value>" syntax, as seen in the keyPredicate-cmplx grammar rule of the Augmented BNF for URI Construction listing in URI Syntax (section 2.2.3.1). However, the representation, which only specifies the value of the property, is the canonical representation for single property EntityKeys.

keyPredicate-cmplx: Identifies an EntityKey consisting of more than one property of the EntityType.  The order in which the properties of a compound EntityKey appear in the URI MUST NOT be significant.

serviceOperation-collEt: Identifies a FunctionImport in an Entity Data Model, as seen in [MC-CSDL], which returns a collection of entities with each entity in the same EntitySet.  A Service Operation of this type acts as a pseudo EntitySet in that additional Resource Path (section 2.2.3.3) segments may follow identifying entities or relationships on entities within the collection identified by the Service Operation.

serviceOperation: Identifies a FunctionImport in an Entity Data Model, as seen in [MC-CSDL], which returns any of the following:

§ Primitive type

§ collection of Primitive types

§ a single ComplexType instance

§ collection of ComplexType instances

§ a single EntityType instance

For additional details on the type system (Primitive types, ComplexType, and so on) used by data services, see Message Syntax (section 2.2).

2.2.3.5   Resource Path: Semantics

This section describes the semantics for a base set of data service URIs.  From these base cases, the semantics of longer URIs are defined by composing the rules below.

The URI segments used in this section use Augmented Backus-Naur Form (ABNF), as specified in [RFC5234] syntax and the rules used in the segments are defined in the Augmented BNF for URI Construction listing in URI Syntax (section 2.2.3.1) and in [RFC3986].  Directly beneath each ABNF rule describing a URI there is a description of the semantic meaning for the URI and an example URI derived from the sample Entity Data Model defined in Appendix A: Sample Entity Data Model and CSDL Document.

The following rules are in addition to the grammar rules defined in the following Resource Path Semantics listing:

§ In each of the grammar rules below, the serviceOperation-collEt rule can be substituted for the first occurrence of an entitySet rule in the Resource Path.  This type of a substitution redefines the replaced segment from identifying an EntitySet to identifying a group of entities.

§ Any rule within the Resource Path portion of a data service URI, which identifies an EntitySet or collection of entities, MAY<3> be immediately followed by a parenthesis, as described by the 'paren' rule in the ABNF grammar in URI Format: Resource Addressing Rules (section 2.2.3).

§  URI1 = scheme serviceRoot "/" entitySet

MUST identify all instances of the base EntityType or any of the EntityType's subtypes within the specified EntitySet specified in the last URI segment. 

If the Entity Data Model associated with the data service does not include an EntitySet with the name specified, then this URI (and any URI created by appending additional path segments) MUST be treated as identifying a non-existent resource, as described in Message Processing Events and Sequencing Rules (section 3.2.5).

Example:

§  URI2 = scheme serviceRoot "/" entitySet "(" keyPredicate ")"

MUST identify a single EntityType instance, which is within the EntitySet specified in the URI, where key EntityKey is equal to the value of the keyPredicate specified.

If no entity identified by the keyPredicate exists in the EntitySet specified, then this URI (and any URI created by appending additional path segments) MUST represent a resource that does not exist in the data model.

Example:

Note  The keyPredicate in this example represents an EntityKey made up of a single property (keyPredicate-single) and the type of that property is Edm.String. The literal value of the property is represented using single quotes as per the data literal syntax for Primitive types, as specified in Abstract Type System (section 2.2.2).

§  URI3 = scheme serviceRoot "/" entitySet "(" keyPredicate ")/" entityComplexProperty

MUST identify an instance of a ComplexType on the specified EntityType instance.  URI 2 (shown in the preceding example) describes how an entitySet followed by a keyPredicate identifies an EntityType instance.

Example:

§  URI4 = scheme serviceRoot "/" entitySet "(" keyPredicate ")/" entityComplexProperty "/" entityProperty

MUST identify a property of a ComplexType defined on the EntityType of the entity whose EntityKey value is specified by the keyPredicate and is within the specified EntitySet.

As noted in the Augmented BNF for URI Construction listing in URI Syntax (section 2.2.3.1), a path segment containing only the rule entity Property may append a '/$value' segment.  A $value MUST be interpreted as a dereference operator and indicates only the value of the property that is being addressed (for example, it does not indicate additional metadata or the surrounding envelope).

Example:

Example:

§  URI5 = scheme serviceRoot "/" entitySet "(" keyPredicate ")/" entityProperty

MUST identify a property whose type is an EDMSimpleType on the EntityType instance (identified with EntityKey equal to the specified key predicate) within the specified EntitySet.

As noted in the Augmented BNF for URI Construction listing in URI Syntax (section 2.2.3.1), a path segment containing only the rule entity Property may append a '/$value' segment.  A $value MUST be interpreted as a dereference operator and indicates only the value of the property that is being addressed (for example, it indicates that no additional metadata or surrounding envelope is to be used).

Example:

Example:

§  URI6 = scheme serviceRoot "/" entitySet "(" keyPredicate ")/" entityNavProperty

MUST identify a set of entities or an EntityType instance that is reached via the specified NavigationProperty on the entity identified by the EntitySet name and key predicate specified.

For example, given an association between Customer and Order entities, an Order Entity Type may define a NavigationProperty named "OrderedBy" that represents the Customer instance associated with that particular Order instance.  Similarly, the Customer Entity Type may define a Navigation Property named "Orders" that represents the Order instances associated to that particular Customer instance.

Example:

§  URI7 = scheme serviceRoot "/" entitySet "(" keyPredicate ")/$links/" entityNavProperty

MUST identify the collection of all Links from the specified EntityType instance (identified by the EntitySet name and key predicate specified) to all other entities that can be reached via the Navigation Property.  The path segment following the $links segment specifies the specific association being addressed, which may identify a single or collection of Links.  Therefore, this URI identifies a Link or collection of Links (depending on the association multiplicity defined by the Navigation Property) and not the value of an entity or collection of entities.

Example:

Example:

§  URI8 = scheme serviceRoot "/$metadata"

MUST identify the Entity Data Model Extensions (EDMX) document, as specified in [MC-EDMX], which includes the Entity Data Model represented using a conceptual schema definition language (CSDL), as specified in[MC-CSDL], for the data service.

Example:

§  URI9 = scheme serviceRoot "/$batch"

MUST identify the endpoint of a data service which accepts Batch Requests (section 2.2.7.6).

Example:

§  URI10 = scheme serviceRoot "/" serviceOperation-et

MUST identify a FunctionImport that returns a single EntityType instance.

If no FunctionImport exists in the Entity Data Model associated with the data service which has the same name as specified by the serviceOperation-et rule, then this URI MUST represent a resource that does not exist in the data model.

As per the ABNF grammar in URI Format: Resource Addressing Rules (section 2.2.3), no further Resource Path segments can be composed onto a URI of this form.

§  URI11 = scheme serviceRoot "/" serviceOperation-collCt

MUST identify a FunctionImport which returns a collection of ComplexType instances.

If no FunctionImport exists in the Entity Data Model associated with the data service that has the same name as specified by the serviceOperation-collCt rule, then this URI MUST represent a resource that does not exist in the data model.

As per the ABNF grammar in URI Format: Resource Addressing Rules (section 2.2.3), no further Resource Path segments can be composed onto a URI of this form.

§  URI12 = scheme serviceRoot "/" serviceOperation-ct

MUST identify a FunctionImport which returns a ComplexType instance.

If no FunctionImport exists in the Entity Data Model associated with the data service that has the same name as specified by the serviceOperation-ct rule, then this URI MUST represent a resource that does not exist in the data model.

As per the ABNF grammar in URI Format: Resource Addressing Rules (section 2.2.3), no further Resource Path segments can be composed onto a URI of this form.

§  URI13 = scheme serviceRoot "/" serviceOperation-collPrim

MUST identify a FunctionImport which returns a collection of Primitive type values.  The set of Primitive types supported is specified in URI Format: Resource Addressing Rules (section 2.2.3).

If no FunctionImport exists in the Entity Data Model associated with the data service that has the same name as specified by the serviceOperation-collPrim rule, then this URI MUST represent a resource that does not exist in the data model.

As per the ABNF grammar in URI Format: Resource Addressing Rules (section 2.2.3), no further Resource Path segments can be composed on to a URI of this form.

§  URI14 = scheme serviceRoot "/" serviceOperation-prim

MUST identify a FunctionImport which returns a single Primitive type value.  The set of Primitive types supported is defined in section 2.2.2.

If no FunctionImport exists in the Entity Data Model associated with the data service that has the same name as specified by the serviceOperation-collPrim rule, then this URI MUST represent a resource that does not exist in the data model.

A path segment containing only the rule serviceOperation-prim may append a '/$value' segment.  A $value MUST be interpreted as a dereference operator and indicates only the value of the property that is being addressed (for example, it indicates no additional metadata or surrounding envelope is to be used).

§  URI15 = scheme serviceRoot "/" entitySet count

MUST identify the count of all instances of the base EntityType or any of the EntityType's subtypes within the specified EntitySet specified in the last URI segment.

If the Entity Data Model associated with the data service does not include an EntitySet with the name specified, then this URI MUST be treated as identifying a non-existent resource, as described in Message Processing Events and Sequencing Rules (section 3.2.5).

The $count segment is supported only in version 2.0 of the protocol defined by this specification.

§  URI16 = scheme serviceRoot "/" entitySet "(" keyPredicate ") count

MAY identify the count of a single EntityType instance (the count value SHOULD always equal one), which is within the EntitySet specified in the URI, where key EntityKey is equal to the value of the keyPredicate specified.

If the Entity Data Model associated with the data service does not include an EntitySet instance with the keyPredicate specified, then this URI MUST be treated as identifying a non-existent resource, as described in Message Processing Events and Sequencing Rules (section 3.2.5).

The $value segment is supported only in version 2.0 of the protocol defined by this specification.

§  URI17 = scheme serviceRoot "/" entitySet "(" keyPredicate ")" value

MUST identify the Media Resource [RFC5023] associated with the identified EntityType instance.  The EntityType that defines the entity identified MUST be annotated with the 'HasStream' attribute, as defined in Conceptual Schema Definition Language Document for Data Services (section 2.2.3.7.2).  As shown in the ABNF grammar in section 2.2.3.1, the "value" segment shown in this URI MAY be appended to any path which identifies a single entity.

Example:

Listing: Resource Path Semantics

2.2.3.6   Query Options

As described in section 2.2.3, all data services MUST follow the query string parsing and construction rules as defined in this section and its subsections.

The Query Options section of a data service URI specifies three types of information: System Query Options (2.2.3.6.1), Custom Query Options (2.2.3.6.2), and Service Operation Parameters (2.2.3.6.3).  System Query Options and Service Operation Parameters MUST conform to the following rules:

§ Any number of the query options MAY<4> be specified in a data service URI.

§ The order of Query Options within a URI MUST be insignificant.

§ Query option names and values MUST be treated as case sensitive.

§ System Query Option names MUST begin with a '$', as seen in System Query Option (section 2.2.3.6.1).

§ Custom Query Options (section 2.2.3.6.2) MUST NOT begin with a '$'.

2.2.3.6.1   System Query Options

System Query Options in a data service URI, defined in URI Format: Resource Addressing Rules (section 2.2.3), are directives, defined by this document, that a client MAY specify to control the amount and order of the data that a data service returns for the resource identified by the URI.  The names of all System Query Options are prefixed with a '$' character.

A data service MAY<5> support some or all of the System Query Options defined in this document.  If a data service does not support a System Query Option, it MUST reject any requests which contain the unsupported option, as seen in Message Processing Events and Sequencing Rules (section 3.2.5) for HTTP-specific server details.

The following Supported System Query Options table summarizes the System Query Options defined in this document.

If a System Query Option is included in a data service URI identifying a resource that is incompatible with the query option, as shown in the following System Query Options Supported per URI table, then the URI MUST be considered malformed.

Table: Summary of Supported System Query Options

In the following System Query Options Supported per URI table, the column labels ( URI1, URI2, and so on) refer to the Resource Path Semantics table in URI types defined by the grammar rules in Resource Path: Semantics (section 2.2.3.5).  A cell value of 'yes' indicates the System Query Option MAY be used with the URI type associated with the column.  A cell value of 'no' indicates that if the System Query Option is present on a URI of the form indicated by the associated column, the URI MUST be considered malformed.

Figure 2: Table: System Query Options Supported Per URI

Note 1: The NavigationProperty in the final path segment of the URI should be assumed to identify a single EntityType instance.

Note 2: The NavigationProperty in the final path segment of the URI should be assumed to identify a set of entities.

Note 3: The $inlinecount System Query Option is supported only in version 2.0 of the extensions defined by this specification to the AtomPub protocol.

2.2.3.6.1.1   Common Expression Syntax

The filter and orderby query options are specified in the data service URI via the common expression syntax defined in following Augmented BNF for Query Option Expressions listing.

Listing: Augmented BNF for Query Option Expressions

A data service MAY<6> support some or all of the boolCommonExpressions for the filter ($filter) system query option.  A data service MAY<7> support some or all of the commonExpressions for the orderby ($orderby) query option.

If a data service does not support a given expression, it MUST reject any requests which contain the unsupported expression.

A data service MAY reject any requests that contain expressions not defined in this document.

Common Expressions SHOULD be constructed and evaluated according to the rules defined in Common Expression Syntax (section 2.2.3.6.1.1) for each specific expression type.

2.2.3.6.1.1.1   Expression Construction and Evaluation Rules

commonExpression: A data service MAY support the commonExpression common expression.  If supported, a commonExpression MUST represent any and all supported common expression types.

boolCommonExpression: A data service MAY support the boolCommonExpression common expression.  If supported, a boolCommonExpression MUST be a common expression that evaluates to the EDM Primitive type Edm.Boolean.

parenExpression: A data service MAY support the enclosing of expressions in parentheses.  This expression is represented as a parenExpression common expression in the common expression syntax.

If supported, a parenExpression MUST be evaluated by evaluating the expression with the parentheses, starting with the innermost parenthesized expressions and proceeding outwards, following proper precedence rules where parentheses override any other operator precedence. The result of the parenExpression MUST be the result of the evaluation of the contained expression.

boolParenExpression: A data service MAY support the enclosing of Boolean expressions in parentheses.  This expression is represented as a boolParenExpression common expression in the common expression syntax.

If supported, a boolParenExpression MUST be evaluated by evaluating the expression with the parentheses. The result of the boolParenExpression MUST be the result of the evaluation of the contained expression and MUST be of the EDM Primitive type Edm.Boolean.

addExpression: A data service MAY support the binary addition operator.  The operation of adding two expressions is represented as an addExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<8> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

The addExpression SHOULD not be supported for any other EDM Primitive types.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Binary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the addExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the addExpression, according to the rules of [IEEE754-2008] for the addition operation.  Further, the data service MAY support evaluating operands with null values following the rules defined in Lifted operators (section 2.2.3.6.1.1.5).

subExpression: A data service MAY support the binary subtraction operator.  The operation of subtracting two expressions is represented as a subExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<9> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

The subExpression SHOULD not be supported for operands of any other EDM Primitive type.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the subExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the subExpression, according to the rules of [IEEE754-2008] for the subtraction operation.  Further, the data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

mulExpression: A data service MAY support the binary multiplication operator.  The operation of multiplying two expressions is represented as a mulExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<10> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

The mulExpression SHOULD not be supported for operands of any other EDM Primitive type.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the mulExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the mulExpression, according to the rules of [IEEE754-2008] for the multiplication operation.  Further, the data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

divExpression: A data service MAY support the binary division operator.  The operation of dividing two expressions is represented as a divExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<11> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

The divExpression SHOULD not be supported for operands of any other EDM Primitive type.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the divExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the divExpression, according to the rules of [IEEE754-2008] for the division operation.  Further, the data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

modExpression: A data service MAY support the binary remainder operator.  The operation of computing the remainder of two expressions is represented as a modExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<12> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

The modExpression SHOULD not be supported for operands of any other EDM Primitive type.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the modExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the modExpression, according to the rules of [IEEE754-2008] for the remainder operation.  Further, the data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

negateExpression: A data service MAY support the unary negate operator.  The operation of negating an expression is represented by the negateExpression common expression in the common expression syntax.  If this operation is supported, the data service MAY<13> support some or all of the common expressions as operands of the operation.  The operand expression MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

The data service SHOULD not support operand expressions of any other EDM Primitive type for the negateExpression.

If supported, a data service SHOULD follow the unary numeric promotion rules defined in Operator Precedence (section 2.2.3.6.1.1.3) to implicitly convert the operand to a supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the negateExpression MUST be the same type as the operand after binary numeric promotion rules have been applied to the operand.

If supported, the data service SHOULD evaluate the operation represented by the negateExpression by subtracting the operand value from zero.   This result of evaluating the negateExpression SHOULD always be equal to the result of evaluating the subExpression where one operand is the value zero and the other is the value of the operand.

The data service MAY support evaluating an operand with a null value following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

andExpression: A data service MAY support the binary logical-and operator.  The operation of evaluating whether two expressions both evaluate to the value of true is represented by the andExpression common Expression in the common expression syntax . If this operation is supported, the data service MAY<14> support some or all of the boolCommonExpressions expressions as operands of the operation.  Those operand expressions MUST evaluate to the EDM Primitive types of Edm.Boolean. The andExpression SHOULD not be supported for operands of any other EDM Primitive types.

The EDM Primitive type of the result of evaluating the andExpression MUST be Edm.Boolean.

If supported, a data service MUST evaluate the expression to the value of true if the values of the operands are both true after being evaluated.  If either operand is false after being evaluated, the expression MUST evaluate to the value of false.

The data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

orExpression: A data service MAY support the binary logical-or operator.  The operation of evaluating whether at least one of two expressions evaluate to the value of true is represented by the orExpression common Expression in the common expression syntax . If this operation is supported, the data service MAY<15> support some or all of the boolCommonExpressions common expressions as operands of the operation.  Those operand expressions MUST evaluate to the EDM Primitive types of Edm.Boolean. The orExpression SHOULD not be supported for operands of any other EDM Primitive types.

The EDM Primitive type of the result of evaluating the orExpression MUST be Edm.Boolean.

If supported, a data service MUST evaluate the expression to the value of true if at least one of the operands is true after being evaluated.  If both operands are false after being evaluated, the expression MUST evaluate to the value of false.

The data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

memberExpression: A data service MAY support the referencing of a Navigation, Complex, or Simple Property of an EntityType.  This is represented by the memberExpression common expression in the common expression syntax.

If supported, the common expression which is the target of the memberExpression MUST be a known Edm Entity or ComplexType.  If supported, the memberExpression MAY reference an entity NavigationProperty (entityNavProperty, as specified in Resource Path: Construction Rules (section 2.2.3.4)), or an Entity Complex type property (entityComplextProperty, as specified in (Resource Path: Construction Rules (section 2.2.3.4)), or an Entity Simple Property, as specified in Resource Path: Construction Rules (section 2.2.3.4). For entity NavigationProperties, the target relationship end must have a cardinality of 1 (single entity, mandatory) or 0..1 (single entity, optional).

The type of the result of evaluating the memberExpression MUST be the same type as the property reference in the memberExpression.

The data service MAY support evaluating a  memberExpression where instance values of a property are null following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

firstMemberExpression: A data service MAY support the referencing of a Navigation, Complex, or Simple Property of the Edm Entity or ComplexType represented by the last segment in the navigation portion of the URI.  This is represented by the firstMemberExpression common expression in the common expression syntax.

If supported, the memberExpression MAY reference an Entity Navigation property (entityNavProperty, as specified in Resource Path: Construction Rules (section 2.2.3.4)), or an Entity Complex type property (entityComplextProperty, as specified in Resource Path: Construction Rules (section 2.2.3.4)), or an Entity Simple Property, as specified in Resource Path: Construction Rules (section 2.2.3.4). For Entity NavigationProperties, the target relationship end must have a cardinality of 1 (single entity, mandatory) or 0..1 (single entity, optional).

The type of the result of evaluating the memberExpression MUST be the same type as the property reference in the memberExpression.

The data service MAY support evaluating a  memberExpression where instance values of a property are null following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

boolPrimitiveMemberExpression: A data service MAY support the referencing of a Boolean Simple Property of an Edm Entity or ComplexType.  This is represented by the boolPrimitiveMemberExpression common expression in the common expression syntax.

The type of the result of evaluating the boolPrimitiveMemberExpression MUST be EDM Primitive type Edm.Boolean.

The data service MAY support evaluating a Boolean memberExpression where the property instance value is null following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

firstBoolPrimitiveMemberExpression: A data service MAY support the referencing of a Boolean Simple Property of an Edm Entity or ComplexType represented by the last segment in the navigation portion of the URI.  This is represented by the firstBoolPrimitiveMemberExpression common expression in the common expression syntax.

The type of the result of evaluating the boolPrimitiveMemberExpression MUST be EDM Primitive type Edm.Boolean.

The data service MAY support evaluating a Boolean memberExpression where the property instance value is null following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

eqExpression: A data service MAY support the binary equality operator.  The operation of evaluating whether two expressions are equal is represented as an eqExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<16> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of a known EntityType (see [MC-CSDL] for the definition of equality between two EntityType instances) or one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

§ Edm.String

§ Edm.DateTime

§ Edm.Guid

§ Edm.Binary

The eqExpression SHOULD NOT be supported for any other EDM Primitive types.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type. The EDM Primitive type of the result of evaluating the eqExpression MUST be Edm.Boolean.

If supported, a data service MUST return a value of true if the values of the operands are equal and false if they are not equal.  If the type of the operands is a known EntityType, then a value of true MUST be returned if the operand expressions, once evaluated, represent the same entity instance.  Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

neExpression: A data service MAY support the binary non-equality operator.  The operation of evaluating whether two expressions are not equal is represented as an neExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<17> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of a known EntityType or one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

§ Edm.String

§ Edm.DateTime

§ Edm.Guid

§ Edm.Binary

The neExpression SHOULD not be supported for any other EDM Primitive types.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the neExpression MUST be Edm.Boolean.

If supported, a data service MUST return a value of true if the values of the operands are not equal, false if they are equal.  If the type of the operands is a known EntityType, then a value of true MUST be returned if the operand expressions once evaluated do not represent the same entity instance.  Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

ltExpression: A data service MAY support the binary less than operator.  The operation of evaluating whether one expression is less than the other expression is represented as an ltExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<18> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

§ Edm.String

§ Edm.DateTime

§ Edm.Guid

The ltExpression SHOULD not be supported for any other EDM Primitive types.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the ltExpression MUST be Edm.Boolean.

If supported, a data service MUST return a value of true if the value of the first operand is less than the value of the second operand, false if not.  Actual ordering and comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when ordering and comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

leExpression: A data service MAY support the binary less than or equal to the operator.  The operation of evaluating whether one expression is less than or equal to the other expression is represented as an leExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<19> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

§ Edm.String

§ Edm.DateTime

§ Edm.Guid

The leExpression SHOULD not be supported for any other EDM Primitive types.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the leExpression MUST be Edm.Boolean.

If supported, a data service MUST return a value of true if the value of the first operand is less than or equal the value of the second operand, and false if not.  Actual ordering and comparison of values is data service specific and no semantics for doing so are mandated, however a data service MUST always use consistent semantics when ordering and comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

gtExpression: A data service MAY support the binary greater than operator.  The operation of evaluating whether one expression is greater than the other expression is represented as an gtExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<20> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

§ Edm.String

§ Edm.DateTime

§ Edm.Guid

The gtExpression SHOULD not be supported for any other EDM Primitive types.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the gtExpression MUST be Edm.Boolean.

If supported, a data service MUST return a value of true if the value of the first operand is greater than or equal to the value of the second operand, and false if not.  Actual ordering and comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when ordering and comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

geExpression: A data service MAY support the binary greater than or equal operator.  The operation of evaluating whether one expression is greater than or equal to the other expression is represented as a geExpression common expression in the common expression syntax. If this operation is supported, the data service MAY<21> support some or all of the common expressions as operands of the operation.  Those operand expressions MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Int32

§ Edm.Int64

§ Edm.String

§ Edm.DateTime

§ Edm.Guid

The geExpression SHOULD not be supported for any other EDM Primitive types.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Unary numeric promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the geExpression MUST be Edm.Boolean.

If supported, a data service MUST return a value of true if the value of the first operand is greater than or equal to the value of the second operand, and false if not.  Actual ordering and comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when ordering and comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

notExpression: A data service MAY support the unary logical negation operator.  The operation of logically negating a expression is represented by the notExpression common expression in the common expression syntax.  If this operation is supported, the data service MAY<22> support some or all of the common expressions as operand values of the operation as long as the operand expression evaluates to a value of the EDM Primitive type Edm.Boolean. The data service SHOULD not support operand expressions of any other EDM Primitive type for the notExpression.

The EDM Primitive type of the result of evaluating the notExpression MUST be Edm.Boolean.

If supported, the data service MUST evaluate the logical negation operation by returning false if the operand value is true and returning true if the operand value is false.

The data service MAY support evaluating an operand with a null value following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

isofExpression: A data service MAY support the isof operation.  The operation of checking whether an instance is compatible with a given type is represented by the isofExpression common expression in the common expression syntax.  If this operation is supported, the data service MAY<23> support some or all of the common expressions as the first operand value.  In addition, the data service MAY support the first operand as being optional. In the case where it is not included, then the is of operation is interpreted to apply to the entity instance specified by the navigation portion of the request URI.  The second operand MUST be a stringLiteral that represents the name of a known entity or EDM Primitive type.

The EDM Primitive type of the result of evaluating the isofExpression MUST be Edm.Boolean.

If supported, the data service MUST evaluate the isofExpression to return a value of true if the targeted instance can be converted to the specified type.  If the conversion is not allowed, then the expression MUST be evaluated to the expression of false.

The data service MAY support evaluating an operand with a null value following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

castExpression: A data service MAY support the cast expression.  The operation of converting an expression to a given type is represented by the castExpression common expression in the common expression syntax.  If this operation is supported, the data service MAY<24> support some or all of the common expressions as the first operand value.  In addition, the data service MAY support the first operand as being optional. In the case where it is not included, then the cast operation is interpreted to apply to the entity instance specified by the navigation portion of the request URI.  The second operand MUST be a stringLiteral which represents the name of a known entity or EDM Primitive type to convert the first operand to.

The type of the result of evaluating the castExpression MUST be the same type as represented by the string literal value from the second operand.  A data service MAY support any cast operations where there exists an explicit conversion from the targeted instance (first operand) to the type represented by second operand.  In all other cases, the data service SHOULD NOT support the specified cast operation.

The data service MAY support evaluating an operand with a null value following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

boolCastExpression: A data service MAY support the Boolean cast expression.  The operation of converting an expression to a Boolean value is represented by the boolCastExpression common expression in the common expression syntax.  If this operation is supported, the data service MAY<25> support some or all of the common expressions as the first operand value.  In addition, the data service MAY support the first operand as being optional. In the case where it is not included, then the cast operation is interpreted to apply to the entity instance specified by the navigation portion of the request URI.  The second operand MUST be the stringLiteral "Edm.Boolean".

The type of the result of evaluating the boolCastExpression MUST be EDM Primitive type Edm.Boolean.  A data service MAY support any cast operations where there exists an explicit conversion from the targeted instance (first operand) to the EDM Primitive type Edm.Boolean.  In all other cases, the data service SHOULD NOT support the specified cast operation.

The data service MAY support evaluating an operand with a null value following the rules defined in Binary numeric promotions (section 2.2.3.6.1.1.5).

boolLiteralExpression: A data service MAY support expressions which are literals representing a Boolean value.  These expressions are represented by the boolLiteralExpression common expression in the common expression syntax.

If supported, the type of the boolLiteralExpression MUST always be the EDM Primitive type Edm.Boolean.

literalExpression: A data service MAY support expressions which are literals.  These expressions are represented by the literalExpression common expression in the common expression syntax.

If supported, the type of the literalExpression MUST be the EDM Primitive type for the lexical representation of the literal, as specified in Abstract Type System (section 2.2.2).

methodCallExpression: A data service MAY support the methodCallExpression common expression.  If supported, a methodCallExpression MUST represent a method call in the common expression syntax.

boolMethodCallExpression: A data service MAY support the boolMethodCallExpression common expression.  If supported, a boolMethodCallExpression MUST be a method call expression that evaluates to the EDM Primitive type Edm.Boolean.

endsWithMethodCallExpression: A data service MAY support the EndsWith method.  This method call is represented as an endsWithMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<26> support some or all of the common expressions as the parameters of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The endsWithMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the endsWithMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.Boolean.

If supported, the data service SHOULD evaluate the method call represented by the endsWithMethodCallExpression by returning a Boolean value indicating whether the end of the first parameter value matches the second parameter value.  Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary numeric promotions (section 2.2.3.6.1.1.5) to implicitly convert the parameters to a supported EDM Primitive type.

indexOfMethodCallExpression: A data service MAY support the IndexOf method.  This method call is represented as an indexOfMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<27> support some or all of the common expressions as the parameters of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The indexOfMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the indexOfMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the indexOfMethodCallExpression by returning an integer value indicating the index of the first occurrence of the second parameter value in the first parameter value.  If no index is found, a value of -1 SHOULD be returned.  Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary numeric promotions (section 2.2.3.6.1.1.5) to implicitly convert the parameters to a supported EDM Primitive type.

replaceMethodCallExpression: A data service MAY support the replace method.  This method call is represented as a replaceMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<28> support some or all of the common expressions as the parameters of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The replaceMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the replaceMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the replaceMethodCallExpression by returning a string value with all occurrences of the second parameter value replaced by the third parameter value in the first parameter value.  Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters, as defined in Binary numeric promotions (section 2.2.3.6.1.1.5), to implicitly convert the parameters to a supported EDM Primitive type.

startsWithMethodCallExpression: A data service MAY support the startswith method.  This method call is represented as a startsWithMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<29> support some or all of the common expressions as the parameters of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The startsWithMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the startsWithMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.Boolean.

If supported, the data service SHOULD evaluate the method call represented by the startsWithMethodCallExpression by returning a Boolean value indicating whether the beginning of the first parameter values matches the second parameter value.  Actual comparison of values is data service-specific and no semantics for doing so are mandated, however a data service MUST always use consistent semantics when comparing values.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary numeric promotions (section 2.2.3.6.1.1.5) to implicitly convert the parameters to a supported EDM Primitive type.

toLowerMethodCallExpression: A data service MAY support the tolower method.  This method call is represented as a toLowerMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<30> support some or all of the common expressions as the parameter of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The toLowerMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the toLowerMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the toLowerMethodCallExpression by returning a string value with the contents of the parameter value converted to lower case.  Actual definition of lower case is data service-specific and no semantics are mandated; however, a data service MUST always use consistent semantics when converting to lower case.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters, defined in Binary numeric promotions (section 2.2.3.6.1.1.5), to implicitly convert the parameters to a supported EDM Primitive type.

toUpperMethodCallExpression: A data service MAY support the toupper method.  This method call is represented as a toUpperMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<31> support some or all of the common expressions as the parameter of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The toUpperMethodCallExpression SHOULD NOT be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the toUpperMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the toUpperMethodCallExpression by returning a string value with the contents of the parameter value converted to upper case.  Actual definition of upper case is data service-specific and no semantics are mandated; however, a data service MUST always use consistent semantics when converting to upper case.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters, defined in Binary numeric promotions (section 2.2.3.6.1.1.5), to implicitly convert the parameters to a supported EDM Primitive type.

trimMethodCallExpression: A data service MAY support the trim method.  This method call is represented as a trimMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<32> support some or all of the common expressions as the parameter of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The trimMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the trimMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the trimMethodCallExpression by returning a string value with the contents of the parameter value with all leading and trailing white-space characters removed.  Actual definition of white space is data service-specific and no semantics are mandated; however, a data service MUST always use consistent semantics when identifying white space.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters, defined in Binary numeric promotions (section 2.2.3.6.1.1.5), to implicitly convert the parameters to a supported EDM Primitive type.

substringMethodCallExpression: A data service MAY support the substring method.  This method call is represented as a substringMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<33> support some or all of the common expressions as the parameters of this method.  The first parameter expression MUST evaluate to a value of the EDM Primitive type Edm.String. The second and third parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.Int32.

The substringMethodCallExpression SHOULD NOT be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the substringMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the substringMethodCallExpression by returning the string value starting at the character index specified by the second parameter value in the first parameter string value.  If the optional third parameter is specified, then the resulting string should be the length (in characters) of the third parameter value. Otherwise, the entire string from the specified starting index is returned.

subStringOfMethodCallExpression: A data service MAY support the substringof method.  This method call is represented as a substringOfMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<34> support some or all of the common expressions as the parameters of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The substringOfMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the substringOfMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.Boolean.

If supported, the data service SHOULD evaluate the method call represented by the substringOfMethodCallExpression by returning a Boolean value indicating whether the second parameter string value occurs in the first parameter string value. Actual comparison of values is data service-specific and no semantics for doing so is mandated; however, a data service MUST always use consistent semantics when comparing values.

concatMethodCallExpression: A data service MAY support the  concat method.  This method call is represented as a concatMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<35> support some or all of the common expressions as the parameters of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The concatMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the concatMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the concatMethodCallExpression by returning a string value which is the first and second parameter values merged together with the first parameter value coming first in the result.

lengthMethodCallExpression: A data service MAY support the  Length method.  This method call is represented as a lengthMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<36> support some or all of the common expressions as the parameter of this method.  The parameter expressions MUST evaluate to a value of the EDM Primitive type Edm.String.

The lengthMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types. If supported, the EDM Primitive type of the result of evaluating the lengthMethodCallExpression SHOULD be a value of the EDM Primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the lengthMethodCallExpression by returning the number of characters in the specified parameter value.  Actual definition of how to calculate string length is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when calculating the length.

yearMethodCallExpression: A data service MAY support the year method.  This method call is represented as a yearMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<37> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of the EDM Primitive type Edm.DateTime.

The yearMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types.

If supported, the EDM Primitive type of the result of evaluating the yearMethodCallExpression SHOULD be the EDM Primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the yearMethodCallExpression by returning the year component value of the parameter value.

monthMethodCallExpression: A data service MAY support the month method.  This method call is represented as a monthMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<38> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of the EDM Primitive type Edm.DateTime.

The monthMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types.

If supported, the EDM Primitive type of the result of evaluating the monthMethodCallExpression SHOULD be the EDM Primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the monthMethodCallExpression by returning the month component value of the parameter value.

dayMethodCallExpression: A data service MAY support the day method.  This method call is represented as a dayMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service<39> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of the EDM Primitive type Edm.DateTime.

The dayMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types.

If supported, the EDM Primitive type of the result of evaluating the dayMethodCallExpression SHOULD be the EDM Primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the dayMethodCallExpression by returning the day component value of the parameter value.

hourMethodCallExpression: A data service MAY support the  hour method.  This method call is represented as an hourMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<40> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of the EDM Primitive type Edm.DateTime.

The hourMethodCallExpression SHOULD NOT be supported for parameters of any other EDM Primitive types.

If supported, the EDM Primitive type of the result of evaluating the hourMethodCallExpression SHOULD be the EDM Primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the hourMethodCallExpression by returning the hour component value of the parameter value using a 24-hour range to cover an entire day without an AM/PM indicator and by starting at 0.

minuteMethodCallExpression: A data service MAY support the  minute method.  This method call is represented as a minuteMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<41> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of the EDM Primitive type Edm.DateTime.

The minuteMethodCallExpression SHOULD NOT be supported for parameters of any other EDM Primitive types.

If supported, the EDM Primitive type of the result of evaluating the minuteMethodCallExpression SHOULD be the EDM Primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the minuteMethodCallExpression by returning the minute component value of the parameter value.

secondMethodCallExpression: A data service MAY support the  second method.  This method call is represented as a secondMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<42> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of the EDM Primitive type Edm.DateTime.

The secondMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types.

If supported, the EDM Primitive type of the result of evaluating the secondMethodCallExpression SHOULD be the EDM Primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the secondMethodCallExpression by returning the second component value of the parameter value.

roundMethodCallExpression: A data service MAY support the  round method.  This method call is represented as a roundMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<43> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

The roundMethodCallExpression SHOULD NOT be supported for parameters of any other EDM Primitive types.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary numeric promotions (section 2.2.3.6.1.1.5) to implicitly convert the parameters to a supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the roundMethodCallExpression MUST be the same type as the parameter.

If supported, the data service SHOULD evaluate the method call represented by the roundMethodCallExpression by returning the nearest integral value to the parameter value, following the rules defined in [IEEE754-2008] for the rounding operation.

floorMethodCallExpression: A data service MAY support the floor method.  This method call is represented as a floorMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<44> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

The floorMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary numeric promotions (section 2.2.3.6.1.1.5) to implicitly convert the parameters to a supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the floorMethodCallExpression MUST be the same type as the parameter after the promotion rules have been applied.

If supported, the data service SHOULD evaluate the method call represented by the floorMethodCallExpression by returning the largest integral value less than or equal to the parameter value, following the rules defined in [IEEE754-2008] for the floor operation.

ceilingMethodCallExpression: A data service MAY support the ceiling method.  This method call is represented as a ceilingMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY<45> support some or all of the common expressions as the parameter of this method.  The parameter expression MUST evaluate to a value of one of the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

The ceilingMethodCallExpression SHOULD not be supported for parameters of any other EDM Primitive types.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary numeric promotions (section 2.2.3.6.1.1.5) to implicitly convert the parameters to a supported EDM Primitive type.  The EDM Primitive type of the result of evaluating the floorMethodCallExpression MUST be the same type as the parameter after the promotion rules have been applied.

If supported, the data service SHOULD evaluate the method call represented by the ceilingMethodCallExpression by returning the smallest integral value greater than or equal to the parameter value, following the rules defined in [IEEE754-2008] for the ceiling operation.

2.2.3.6.1.1.2   Operator Precedence

The following Operator Precedence for Query Option Expressions table summarizes the precedence of operators in the common expression syntax.   Operators are listed by operator category in order of precedence from highest to lowest. Operators in the same category have equal precedence.

Table: Operator Precedence for Query Option Expressions

A data service MAY<46> support some or all of the common expressions that represent the operators above.  For supported operators, the data service SHOULD evaluate the operators in a common expression in order of precedence of operator category.

2.2.3.6.1.1.3   Unary numeric promotions

A data service MAY support unary numeric promotions for the negation operator (negateExpression common expressions).  Unary promotions consist of converting operands of type Edm.Byte or Edm.Int16 to Edm.Int32 and Edm.Single to Edm.Double.

2.2.3.6.1.1.4   Binary numeric promotions

A data service MAY support binary numeric promotion for operands of the following operations:

Table: Operations Which Support Binary Numeric Promotion

If supported, binary numeric promotion SHOULD implicitly convert both operands to a common type and, in the case of the non-relational operators, also become the return type.

If supported, a data service SHOULD support binary numeric promotion for the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Byte

§ Edm.Int16

§ Edm.Int32

§ Edm.Int64

If supported, binary numeric promotion SHOULD consist of the application of the following rules in the order specified:

§ If either operand is of type Edm.Decimal, the other operand is converted to Edm.Decimal unless it is of type Edm.Single or Edm.Double.

§ Otherwise, if either operand is Edm.Double, the other operand is converted to type Edm.Double.

§ Otherwise, if either operand is Edm.Single, the other operand is converted to type Edm.Single.

§ Otherwise, if either operand is Edm.Int64, the other operand is converted to type Edm.Int64.

§ Otherwise, if either operand is Edm.Int32, the other operand is converted to type Edm.Int32

§ Otherwise, if either operand is Edm.Int16, the other operand is converted to type Edm.Int16.

§ If binary numeric promotion is supported, a data service SHOULD use a castExpression to promote an operand to the target type.

2.2.3.6.1.1.5   Lifted operators

A data service MAY support the allowance of operators that operate on EDM Primitive types to also be used with nullable forms of those types for the following operations:

Table: Lifted operators

§ If supported, for unary operators, a data service MUST return the value null if the operand value is null.

§ If supported, for binary operators, a data service MUST return the value null if either operand value is null.

§ If supported, for relational operators, a data service MUST return the value false if one or both of the operands is null.

§ If supported, for equality operators, a data service MUST consider two null values equal and a null value unequal to any non-null value.

§ If supported, for logical operators, a data service MUST return the value null if either operand value is null.

§ If supported, for member operators, a data service MUST return null if any of the NavigationProperties are null.

§ If supported, for  Boolean expressions evaluated to the value of null, a data service MUST return the value of false.

2.2.3.6.1.1.6   Numeric promotions for method call parameters

A data service MAY support numeric promotions for method call parameters.

If supported, a data service SHOULD support binary numeric promotions for the following EDM Primitive types:

§ Edm.Decimal

§ Edm.Double

§ Edm.Single

§ Edm.Byte

§ Edm.Int16

§ Edm.Int32

§ Edm.Int64

If supported, numeric promotions for method parameters SHOULD consist of the application of  the following rules in the order specified:

§ If the method parameter is of type Edm.Decimal, the parameter value expression is converted to Edm.Decimal, unless it is of type Edm.Single or Edm.Double.

§ Otherwise, if the method parameter is Edm.Double, the parameter value expression is converted to type Edm.Double.

§ Otherwise, if the method parameter is Edm.Single, the parameter value expression is converted to type Edm.Single.

§ Otherwise, if the method parameter is Edm.Int64, the parameter value expression is converted to type Edm.Int64.

§ Otherwise, if the method parameter is Edm.Int32, the parameter value expression is converted to type Edm.Int32

§ Otherwise, if the method parameter is Edm.Int16, the parameter value expression is converted to type Edm.Int16.

§ If numeric promotion for method calls is supported, a data service SHOULD use a castExpression to promote a parameter value expression to the target type.

2.2.3.6.1.2   Evaluating System Query Options

Any combination of the System Query Options defined in this document MAY be present on a valid data service URI.  A data service URI with more than one query option present MUST be evaluated as if the query options were applied to the resource(s) identified by the Resource Path section of the URI, in the following order: $format, $inlinecount, $filter, $orderby, $skiptoken, $skip, $top, $expand.

For example, using data from Appendix A: Sample Entity Data Model and CSDL Document (section 6) , the resource identified by the data service URI http://host/service/Customers?$expand=Orders&$filter=substringof(CompanyName, 'bikes')&$orderby=CompanyName asc&$top=2&$skip=3&$skiptoken='Contoso','AKFNU'&$inlinecount=allpages&$select=CustomerID,CustomerName,Orders is determined as follows:

1.  Start with the set of all EntityType instances in the Customers EntitySet in the data service.

2.  Remove all customer instances that do not have "bikes" in their company name (the entities that do not satisfy the condition in the $filter query option).

3.  Determine the count N of all customers identified in step 2.

4.  Sort the set of customers identified in step 2 in ascending order using the values from the CompanyName property defined on the Customer EntityType.

5.  Seek in to the collection up to the index identified by the $skiptoken query option.  Select all entities at the index through the end of the collection.

6.  Starting from the 4th entity (from the collection returned by step 4), as directed by $skip=3, select the next two entities (for example, the 5th and 6th entity in the set), as directed by $top=2.

7.  Of the two entities returned from step 6, select only the CustomerName and CustomerID properties of the Customer entities and all properties of the Order entities. The preceding URI identifies the two entities (and their related entities) returned from this step.

2.2.3.6.1.3   Expand System Query Option ($expand)

The presence of the $expand System Query Option indicates that entities associated with the EntityType instance or EntitySet, identified by the Resource Path section of the URI, MUST be represented inline instead of as Deferred Content (section 2.2.6.2.6) and Deferred Content (section 2.2.6.3.9).

The following rules supplement the grammar below, which represents the syntax of this System Query Option.

The left most entityNavProperty in an expandClause MUST represent a NavigationProperty defined in the EntityType, or a sub type thereof, associated with the Resource Path section of the URI.  A subsequent NavigationProperty in the same expandClause must represent a NavigationProperty defined on the EntityType, or a sub type thereof, represented by the prior NavigationProperty in the expandClause.

Redundant expandClause rules on the same data service URI  MAY be considered valid, but MUST NOT alter the meaning of the URI.

Examples

For each customer entity within the Customers EntitySet, the value of all associated Orders should be represented inline.

For each Order within the Orders EntitySet, the following should be represented inline:

§ The Order lines associated to the Orders identified by the Resource Path section of the URI and the products associated to each Order line.

§ The customer associated with each Order returned.

2.2.3.6.1.4   Filter System Query Option ($filter)

A data service URI with a $filter System Query Option identifies a subset of the entities in the EntitySet, identified by the Resource Path section of the URI, by only selecting the entities that satisfy the predicate expression specified by the query option.

The syntax of the filter System Query Option is defined as:

Examples:

http://host/service.svc/Orders?$filter=ShipCountry eq 'France'

The set of Order entity instances where the ShipCountry is equal to the value 'France'.

http://host/service.svc/Orders?$filter = Customers/ContactName ne 'Fred'

The set of Order entity instances where the associated Customer entity instance has a ContactName not equal to the value 'Fred'.

The syntax, construction, and evaluation rules for boolCommonExpression are defined in Common Expression Syntax (section 2.2.3.6.1.1).

2.2.3.6.1.5   Format System Query Option ($format)

A data service URI with a $format System Query Option specifies that a response to the request SHOULD use the media type specified by the query option.

If the $format query option is present in a request URI, it SHOULD take precedence over the value(s) specified in the Accept (section 2.2.5.1) request header.

The syntax of the Format System Query Option is defined as follows.

§ If the value of the query option is 'atom', then the media type used in the response MUST be 'application/atom+xml'.

§ If the value of the query option is 'json', then the media type used in the response MUST be 'application/json'.

§ If the value of the query option is 'xml', then the media type used in the response MUST be 'application/xml'.

Examples

http://host/service.svc/Orders?$format=json

The set of Order entities represented using the JSON media type, as specified in [RFC4627].

2.2.3.6.1.6   OrderBy System Query Option ($orderby)

A data service URI with a $orderby System Query Option specifies an expression for determining what values are used to order the entities in the EntitySet, identified by the Resource Path section of the URI).

The syntax of the orderby System Query Option is defined as:

If supported, the data service MUST return the entities, in order, based on the expression specified.    If multiple expressions are specified and a data service supports sorting based on multiple values, then a data service MUST return the entities ordered by a secondary sort for each additional expression specified.

If the expression includes the optional asc clause or if no option is specified, the entities MUST be returned in ascending order. If the expression includes the optional desc clause, the entities MUST be returned in descending order. Actual ordering of results is data service specific and no semantics for doing so are mandated, however a data service MUST always use the same semantics when ordering the results of a URI request.

Examples:

The set of Order entity instances returned in ascending order of the ShipCountry property.

The set of Order entity instances returned in descending order of the  ShipCountry property equal or not equal to the value 'France'.

The syntax, construction, and evaluation rules for commonExpression are defined in Common Expression Syntax (section 2.2.3.6.1.1).

2.2.3.6.1.7   Skip System Query Option ($skip)

A data service URI with a $skip System Query Option identifies a subset of the entities in the collection of entities identified by the Resource Path section of the URI. That subset is defined by seeking N entities into the collection and selecting only the remaining entities (starting with entity N+1).  N is a positive integer specified by this query option.

The value of this query option, referred to as N in the preceding paragraph, MUST be an integer greater than or equal to zero.  If a value less than 0 is specified, the URI should be considered malformed.

If the data service URI contains a $skip query option, but does not contain a $orderby option, then the entities in the set MUST first be fully ordered by the data service.  Such a full order SHOULD be obtained by sorting the entities based on their EntityKey values.  While no ordering semantics are mandated, a data service MUST always use the same semantics to obtain a full ordering for all requests.

The syntax of the Skip System Query Option is defined as follows.

Examples:

The set of Order entities sorted by ShippedDate (descending), starting with the 11th order.

The set of Order Entity Type instances (associated with the Customer Entity Type instance identified by EntityKey value ALFKI) starting with the 11th order.

2.2.3.6.1.8   Top System Query Option ($top)

A data service URI with a $top System Query Option identifies a subset of the entities in the collection of entities, identified by the Resource Path section of the URI. This subset is formed by selecting only the first N items of the set, where  N is a positive integer specified by this query option.

The value of this query option, referred to as N in the preceding paragraph, MUST be an integer greater than or equal to zero.  If a value less than 0 is specified, the URI should be considered malformed.

If the data service URI contains a $top query option, but does not contain a $orderby option, then the entities in the set MUST first be fully ordered by the data service.  Such a full order SHOULD be obtained by sorting the entities based on their EntityKey values.  While no ordering semantics are mandated, a data service MUST always use the same semantics to obtain a full ordering across requests.

The syntax of the Top System Query Option is defined as follows.

Examples:

The first 20 Order entity instances returned in descending order when sorted by the ShippedDate property.

The first 20 Order entity instances returned in order of a sorting scheme determined by the data service.

2.2.3.6.1.9   Skip Token System Query Option ($skiptoken)

The value of a $skiptoken query option is an opaque token that MUST identify a starting point in the collection of entities identified by the URI containing the $skiptoken parameter.  For example, the value of a $skiptoken query option could identify the first entity in a collection, the 3rd entity in a collection containing 10 entities, or any other position within the collection represented by the URI containing the $skiptoken parameter.

Since the value of a $skiptoken query option identifies an index into a collection of entities, a data service URI containing a $skiptoken query option identifies a subset of the entities identified by the Resource Path section of the URI.  The subset identified consists of the entities in the entity set identified by the Resource Path section of the URI, starting from the first entity at the index identified by the value of the $skiptoken query option through the last entity in the entity set.

If the data service URI contains a $skip token query option, but does not contain a $orderby option that identifies a full ordering of the collection of entities identified by the URI, then the entities in the set MUST first be fully ordered by the data service.  Such a full order SHOULD be obtained by sorting the entities based on their EntityKey values.  While no ordering semantics are mandated, a data service MUST always use the same semantics to obtain a full ordering across different requests on the same entity set. The syntax of the Skip Token System Query Option is defined as follows.

Examples:

A subset of the Order entity instances (sorted by the OrderID property) starting from a position in the collection of all Order entities identified by the skip token parameter.

2.2.3.6.1.10   Inlinecount System Query Option ($inlinecount)

A data service URI with an $inlinecount System Query Option specifies that the response to the request MUST include the count of the number of entities in the collection of entities, which are identified by the Resource Path section of the URI after all $filter System Query Options have been applied. A data service MAY support the $inlinecount System Query Option on a RetrieveEntity request. Actual counting of items in the EntitySet is data service specific and no semantics for doing so are mandated. The Inlinecount System Query Option is supported only in version 2.0 of the protocol defined by this specification.

The syntax of the Inlinecount System Query Option is defined as follows.

§ If a value other than "allpages" or "none" is specified, the data service MUST return a 4xx error response code.

§ If a value of "none" is specified, the data service MUST NOT include the count in the response.

For information on including the count in the AtomPub and JSON Serialization Formats, refer to sections 2.2.6.2.8 and 2.2.6.3.9.1.

Examples:

All order instances and the count of all order instances returned.

The first 10 order instances and the count of all order instances returned.

The first 10 order instances and the count of all order instances returned.

All order instances with ShipCountry equal to "France" and the count of all order instances with ShipCountry equal to  "France".

2.2.3.6.1.11   Select System Query Option ($select)

A data service URI with a $select System Query Option identifies the same set of entities as a URI without a $select query option; however, the presence of a $select query option specifies that a response from the data service SHOULD return a subset, as identified by the value of the $select query option, of the properties that would have been returned had the URI not included a $select query option. A data service MAY return properties of the resources identified by the request URI beyond those identified by the $select query option.

The following rules supplement the following grammar  that represents the syntax of this System Query Option. The Select System Query Option is supported only in version 2.0 of the protocol defined by this specification.

§ The left most selectedProperty or selectedNavProperty in a selectedClause MUST be a star or represent a property defined in the EntityType, or a subtype thereof, that is identified by the Resource Path section of the URI.

§ A subsequent selectedProperty or selectedNavProperty in the same selectClause MUST represent a property defined on the EntityType, or a subtype thereof, that is represented by the prior navigation property in the selectClause.

§ For AtomPub formatted responses: The value of a selectQueryOp applies only to the properties returned within the <m:properties> element as specified in section 2.2.6.2.2. For example, if a property of an Entity Type is mapped with the attribute KeepInContent=false, as per Customizable Feeds (section 2.2.6.2.2.1), to an element or attribute in the response, then that property MUST always be included in the response as per its Customizable Feed mapping.

§ For JSON formatted responses: The value of a selectQueryOp applies only to the name/value pairs with a name that does not begin with two consecutive underscore characters.

§ If a property is not requested as a selectItem (explicitly or via a star) it SHOULD NOT be included in the response.

§ If a selectedProperty appears alone as a selectItem in a request URI, then the response MUST contain the value of the property as per the serialization rules defined in sections 2.2.6.2.2 and 2.2.6.3.3.

§ If a star appears alone in a selectClause, all properties on the EntityType within the collection of entities identified by the last path segment in the request URI MUST be included in the response.

§ If a star appears in a selectItem following a selectedNavProperty, all non-navigation properties of the entity or entities represented by the prior selectedNavProperty MUST be included in the response.

§ If a navigation property appears as the last segment of a selectItem and does not appear in a $expand query option, then the entity or collection of entities identified by the navigation property MUST be represented as deferred content as described in sections 2.2.6.2.6 and 2.2.6.3.9.

§ If a navigation property appears as the last segment of a selectItem and the same property is specified as a segment of a path in a $expand query option, then all the properties of the entity identified by the selectItem MUST be in the response. In addition, all the properties of the entities identified by segments in the $expand path after the segment that matched the selectedItem MUST also be included in the response.

§ If multiple selectClause instances exist in a $select query option, then the total set of property values to be returned is equal to the union of the set of properties identified by each selectClause.

§ Redundant selectClause rules on the same URI MAY be considered valid, but MUST NOT alter the meaning of the URI.

The following set of examples use the data model described in Appendix A: Sample Entity Data Model and CSDL Document (section 6)and describe the semantics for a base set of data service URIs using the $select system query option. From these base cases, the semantics of longer URIs are defined by composing the following rules.

Examples

In a response from a data service, only the CustomerID, CompanyName, and Address property values are returned for each customer entity within the Customers EntitySet. When a complex type is selected, all properties defined on that complex type property MUST be returned.

In a response from a data service, only the CustomerID property value and a link to the collection of related entities identified by the Orders navigation property SHOULD be returned for each customer entity within the Customers EntitySet. Note: For the Orders navigation property referenced in the above URI, the $select option only states a link to the corresponding collection of orders will be returned.

In a response from a data service, only the CustomerID property of the customer's entities SHOULD be returned, but all the properties of the entities identified by the Orders and OrderDetails navigation properties SHOULD be returned.

In a response from a data service, all properties are returned for each customer entity within the Customers EntitySet. Note: The star syntax is used to reference all properties of the entity or collection of entities identified by the path of the URI or all properties of a navigation property. In other words, the * syntax causes all properties on an entity to be included without traversing associations.

In a response from a data service, the CustomerID is included as are Order entities with all properties; however, rather than including the fully expanded OrderDetail entities referenced in the expand clause, each Order will contain a link that references the corresponding collection of Order Detail entities.

2.2.3.6.2   Custom Query Options

Custom Query Options provide an extensible mechanism for data service-specific information to be placed in a data service URI query string.  A Custom Query Option is any query option of the form shown by the rule 'customQueryOption' in URI Syntax (section 2.2.3.1).  Custom Query Options MUST NOT begin with a '$' character because the character is reserved for System Query Options, as described in System Query Options (section 2.2.3.6.1).

2.2.3.6.3   Service Operation Parameters

Service Operations represent the FunctionImports, as specified in [MC-CSDL], which accept only Primitive type input parameters defined in the Entity Data Model (EDM) associated with a data service.  If a Function Import requires input parameters, those parameters are passed via query string name/value pairs appended to the data service URI identifying the FunctionImport, as described in Resource Path: Semantics (section 2.2.3.5).

If a Service Operation requires input parameters, a null value may be specified for nullable type parameters by not including the parameter in the query string of the request URI.

To pass parameters to a Service Operation, the following syntax is used.

Listing: ABNF Grammar for Service Operation Parameters

2.2.3.7   Data Service Metadata

2.2.3.7.1   Service Document

For a client to interact with a data service it needs to discover the locations of the available collections of resources.  AtomPub [RFC5023] defines Service Documents to support this discovery process.

The ServiceRoot of a data service MUST identify the Service Document for the data service.

Service Document (section 2.2.6.2.7) describes how Entity Data Model constructs are represented in an AtomPub Service Document.  As per [RFC5023], AtomPub Service Documents MUST be identified with the 'application/atomsvc+xml' mediat type (see [RFC5023] section 8).

Service Document (section 2.2.6.3.12) describes a JSON representation of the data provided by an AtomPub Service Document.  The section also describes how Entity Data Model constructs are represented in the JSON-based Service Document.  JSON Service Documents MUST be identified using the 'application/json' media type.

2.2.3.7.2   Conceptual Schema Definition Language Document for Data Services

All data services SHOULD expose a conceptual schema definition language (CSDL) based metadata endpoint that describes the structure and organization of all the resources exposed as HTTP endpoints by a data service.

This document defines data service-specific extensions and mappings to the constructs of a conceptual schema definition language (CSDL) document.  These extensions MUST be used by a data service in conjunction with the 'dataservices' node defined in [MC-EDMX] such that an Entity Data Model Extensions (EDMX) document is returned from the URI identifying the serviceRoot with a  '/$metadata' path segment appended to the path.

The syntax of the metadata document of a data service returned as the content of the <dataservices> element is described in [MC-EDMX].  As noted in [MC-EDMX], the contents of the <edmx:Edmx> element, in the context of a data service, is an <edmx:DataServices> element which contains one or more conceptual schema definition language (CSDL) documents, as specified in [MC-CSDL], with data service annotations.   The data service conceptual schema definition language (CSDL) annotations are described and highlighted in the XML schema below, as specified in [XMLSCHEMA1].  Elements that do not include data service-specific annotations have been omitted from the XSD document.  See [MC-CSDL] for a complete structural description of a conceptual schema definition language (CSDL) document.

Listing: Conceptual Schema Definition Language Document XSD Schema with Data Service Annotations

The following listing describes the extensions to conceptual schema definition language (CSDL) [MC-CSDL] defined by this document (and shown in the XML schema preceding).

IsDefaultEntityContainer: This attribute MUST be used on an EntityContainer element [MC-CSDL] to indicate which EntityContainer is the default container for the data service.  Each conceptual schema definition language (CSDL) document used to describe a data service MUST mark exactly one EntityContainer with this attribute to denote it is the default.

The valid values for this attribute are 'true' or 'false'.  True signifies the container is the default container and thus does not need to be specified in a Resource Path (section 2.2.3.3).  False signifies the container is not the default and needs to be specified in the URI as per the URI construction rules noted in section 2.2.3.4.

MimeType: This attribute MUST be used on a <Property> element [MC-CSDL] to indicate the media type of the content to be stored in the property being defined by the XML element.  Each <Property> element defining an EDMSimpleType property MAY<47> include exactly one occurrence of this attribute.

Any media type (see [IANA-MMT] ) is a valid value for this attribute.  If this attribute is present on a property definition, then any RetreiveValue (RetrieveValue Request (section 2.2.7.2.5) )  request to for the property MUST return a response which uses the specified mime type as the content type of the response body.

HttpMethod: This attribute MUST be used on a <FunctionImport> element [MC-CSDL] to indicate the HTTP method which is to be used to invoke the ServiceOperation exposing the FunctionImport.  If this attribute is present, the FunctionImport must be callable using the HTTP method specified.

HasStream: This attribute MUST only be used on an <EntityType> element [MC-CSDL].  The presence of this attribute with a value of 'true' on an <EntityType> element states that the Entity Type is associated with a Media Resource (for example, the Entity Type represents a Media Link Entry [RFC5023]).

In addition to the extensions defined in the preceding example, the following mapping of data service constructs to conceptual schema definition language (CSDL) constructs MUST be used by a data service to generate its metadata document.

Service Operations: A Service Operation MUST be represented as a <FunctionImport> element in the data services ' conceptual schema definition language (CSDL) document.  The 'Name' attribute on the element MUST be equal to the name of the Service Operation exposed by the data service.

For an example of a data services EDMX document, see Appendix A: Sample Entity Data Model and CSDL Document (section 6).

The following listing describes the extensions to the entity data model for data services packaging format [MC-EDMX] defined by this document.

DataServiceVersion: This attribute MUST be in the data service metadata namespace (http://schemas.microsoft.com/ado/2007/08/dataservices) and SHOULD be present on a <edmx:DataServices> element [MC-EDMX] to indicate the version of the data service CSDL annotations (attributes in the data service metadata namespace) used by the document. Consumers of a data-service metadata endpoint SHOULD first read this attribute value to determine if they can safely interpret all constructs within the document. The value of this attribute MUST be 1.0 unless a "FC_KeepInContent" Customizable Feed annotation (section 2.2.3.7.2.1) with a value equal to false is present in the CSDL document within the <edmx:DataServices> node. In this case, the attribute value MUST be 2.0.

2.2.3.7.2.1   Conceptual Schema Definition Language Document for Version 2.0 Data Services

This section defines version 2.0 specific extensions (shown in the XML Schema below) to the data service specific metadata document defined in the prior section. These attributes define Customizable Feed property mappings for the AtomPub Format.

Listing: Conceptual Schema Definition Language Document XSD Schema for Version 2.0 Data Services

The Customizable Feed property mappings are used to define a mapping from the properties of an EntityType to elements or attributes in any namespace (including the Atom namespace) in an AtomPub document.  When a property is mapped to an element or attribute of an element, the value for the property is equal to the value of the specified element or attribute in the AtomPub document. An example of a mapped property value is described in Retrieve a Single Entity with a Mapped Property Using the AtomPub Format (section 4.2.2.1). 

The following example shows a Conceptual Schema Definition Langue (CSDL) definition of an Entity Type which includes Customizable Feed property mappings.  The Customizable Feed annotations defined on the Entity Type maps the EmployeeName property of the Employee Entity Type to the <atom:title> element in the Atom namespace .  The example also includes a mapping that specifies the City property of the Address Complex Type property to be represented using the service-defined XML element <emp:Location xmlns:”http://www.microsoft.com”>.

A property mapping MUST be defined as attributes on the Property element of an Entity Type (as in the above example) or on the EntityType element that contains the property to be mapped. A single EntityType property MUST NOT have more than one property mapping defined.

The following listing describes the extensions to conceptual schema definition language (CSDL) [MC-CSDL] defined by this section (and shown in the XML schema preceding). These extensions are only supported in version 2.0 of the extensions defined by this specification to the AtomPub protocol.

FC_ContentKind: The FC_ContentKind attribute specifies the content type of the value of the property being mapped via a Customizable Feed mapping.

The syntax of the FC_ContentKind attribute is defined as:

If the FC_ContentKind property is not defined for an EntityType property, then the value of the property should be assumed to be "text ".

FC_KeepInContent: The FC_KeepInContent attribute specifies if the value of the property on the EntityType of this attribute should be included in both the element specified via the Customizable Feed mapping as well as  the original <m:properties> elements inside of the <atom:content> element, as specified in section 2.2.6.2.2.  The value for the FC_KeepInContent MUST have either the value "true" or "false". If the FC_KeepInContent attribute is not supplied in the mapping, then the data service MUST function as if it were specified with a value of true.

FC_NsPrefix: The FC_NsPrefix attribute specifies the XML namespace prefix to use when an Entity Type’s property is mapped to an XML element in a data service specific namespace. If the FC_TargetPath attribute of the property mapping does not specify an Atom element, then the FC_NsPrefix attribute is optional. If the Entity Type property is being mapped to an AtomPub element, then the FC_NsPrefix attribute MUST NOT be specified. If the FC_TargetPath attribute of the property mapping does not specify an Atom element and the FC_NsPrefix attribute is not supplied, then this document does not mandate a particular prefix be used.

FC_NsUri: The FC_NsUri attribute specifies the namespace to use when the FC_TargetPath of the Entity Type’s property mapping does not specify an AtomPub element. If the FC_TargetPath of the Entity Type’s property mapping does not specify an AtomPub element, then the FC_NsUri attribute MUST be specified on the Entity Type’s definition. If the property is being mapped to an AtomPub element, then the FC_NsUri attribute MUST NOT be specified on the Entity Type’s definition.

FC_TargetPath: The FC_TargetPath attribute identifies the element within an <atom:entry> element to which to map the Entity Type’s property. All mapped properties MUST be mapped to distinct elements within the Atom feed.

If the mapping is not to an Atom element, then the value of the FC_TargetPath MUST identify either an element or an attribute on an element in the AtomPub document. All paths' expressions MUST be rooted at the <entry> element in the Atom feed.

The syntax of the target path is defined as:

A data service SHOULD allow Customizable Feed mappings for distinct Entity Type properties that have partially overlapping FC_TargetPaths (a set of FC_TargetPaths are overlapping when they have some target elements in common). A data service SHOULD support target paths that define elements with mixed content. For example, the following three target paths on distinct properties will create an element structure with overlapping target paths and XMLelements with mixed content:

Resulting Element Structure:

FC_SourcePath: The FC_SourcePath attribute specifies the Entity Type property that is the source property for the mapping.  If the property mapping is specified directly on a property definition (properties are defined using the <Property> element) in the CSDL and the property is a Primitive Property, then the mapping MAY NOT specify the FC_SourcePath attribute and the property identified by the <Property> element MUST be used as the source property of the mapping. If the property mapping is defined on an EntityType element, then the FC_SourcePath attribute MUST be specified and the value MUST be the name of either a Primitive Property defined on the EntityType or a Primitive Property of a ComplexType, which is the type of a Property on the EntityType.

The syntax of the FC_SourcePath is defined as follows:

The FC_SourcePath MUST NOT address an EntityType property that represents a ComplexType.

For example, using the EntityType Employee, as specified in Appendix A: Sample Entity Data Model and CSDL Document (section 6), specifying the City property of an Address ComplexType on an Employee EntityType, an FC_TargetPath value of "Location", an FC_NsPrefix value of "emp", and an FC_NsUri value of "http://www.microsoft.com" would create the following element under the <atom:entry> element.

2.2.3.8   URI Equivalence

When determining if two URIs are equivalent, each URI SHOULD be normalized using the rules specified in [RFC3987] and [RFC3986] and then compared for equality using the equivalence rules specified in  [RFC2616] section 3.2.3.

2.2.3.9   Canonical URIs

For data services conformant with the URI path construction rules defined in this specification, the canonical form of an absolute URI identifying a single EntityType instance MUST be formed by adding a single path segment to the Path Prefix. The path segment MUST be made up of the EntitySet name associated with the entity followed by the key predicate identifying the entity within the set.

For example, the URIs http://host/service.svc/CustomPathPrefix/Customers('ALFKI')/Orders(1) and http://host/service.svc/CustomPathPrefix/Orders(1) identify the same entity in the example data model shown in Appendix A: Sample Entity Data Model and CSDL Document (section 6). Following the rules outlining the canonical form for URIs identifying single entities, the canonical URIs in the example is http://host/service.svc/CustomPathPrefix/Orders(1).

2.2.4   HTTP Methods

This section describes only the HTTP methods defined by this document.  All additional HTTP methods used by this document are specified in [RFC2616].

2.2.4.1   MERGE

Data services support two types of update operations: merge and replace. As per [RFC5023] and described in Update Request Types (section 2.2.7.3), the HTTP PUT method specifies that an update operation SHOULD be carried out using replace semantics.

This section defines a custom  HTTP MERGE method to specify that an update is to be completed using merge semantics.  All the directives defined for the PUT method in HTTP, as specified in [RFC2616], and AtomPub, as specified in [RFC5023], apply equally to the HTTP MERGE method. The only difference between an HTTP requests using MERGE and PUT is client intent.

Since MERGE is not one of the verbs defined in the HTTP specification [RFC2616], using the MERGE verb will likely not flow through network intermediaries as seamlessly as methods defined in HTTP, as specified in [RFC2616]. Data services can support verb tunneling to mitigate this limitation, as defined in Tunneled Requests (section 2.2.7.7).

The semantics of a MERGE request on a data service entity is to merge the content in the request payload with the entities current state. The merging is done by comparing each component (JSON name/value pairs for JSON serializations, XML elements/attributes for XML-based requests, etc) of the request body to the entity as it exists on the server.

If there is a component in the request body that is not defined on the entity being updated then the request MAY be considered malformed.

If there is a component in the request body that does match a component on the entity to be updated then the value of the component in the request body SHOULD replace the matching component of the entity to be updated and the matching process continues with the children of the component from the request body.

The syntax of the HTTP MERGE method is defined as follows.

Listing: ABNF Grammar for MERGE HTTP Method

2.2.5   HTTP Header Fields

The protocol extensions defined in this document use existing headers, as specified in [RFC2616], as well as custom HTTP headers defined in this document.  Some of the headers specified in [RFC2616] are further restrained by this document in how they can be used.  These additionally restrained headers, as well as the custom headers, are defined in this section.

Unless otherwise specified, the headers defined in this document and any tokens, also called tags or directive, used on those headers are defined for use on both requests and responses.

If a client or server receives an HTTP header that is not defined in this section, or if the header is not defined in the current context (for example, receiving a request-only header in a response), the header MUST be interpreted as specified in [RFC2616].

If a client or server receives an HTTP header defined in this section and the header contains an unknown or malformed token, as specified in this section, the request or response that contains the header MUST be considered malformed.

If a client or server receives an HTTP header defined in this section, but header contains a token that is not defined in the current context (for example, receiving a request-only token in a response), the request or response that contains the header and token MUST be considered malformed.

This section defines the syntax of the HTTP headers defined in this section using the Augmented Backus-Naur Form (ABNF) syntax, as specified in [RFC5234].  Any ABNF syntax rules that are not specified in [RFC5234] use the ABNF extensions that are specified in [RFC2616].

The grammars in this section is word-based. Except where noted otherwise, linear white space (LWS), as specified in [RFC2616], can be included between any two adjacent words (token or quoted-string), and between adjacent words and separators without changing the interpretation of a field. At least one delimiter (LWS and/or separators) MUST exist between any two tokens, as specified in [RFC2616], because they would otherwise be interpreted as a single token.

2.2.5.1   Accept

A primary goal of data services is to allow a client of the service to focus on the data being transmitted and not be required to understand a single data format.  As such, the protocol extensions defined in this document enable exchanging resources using AtomPub semantics in multiple serialization formats (AtomPub, JSON, etc).

The nature of the client application using a data service and its runtime environment determines which format is best.  For example, Asynchronous JavaScript (AJAX)-based applications that run inside web browsers may find JSON easier to use because this format can be directly turned into JavaScript objects. On the other hand, a client application may be written with a language/runtime library that has a rich, built-in XML parser, making an XML-based format an appropriate choice.

The extensions defined in this document use the Accept request header field, as specified in [RFC2616].  Once a requested format is determined using the rules specified in [RFC2616], the following Accept Request Header to Content-Type Response Header Mapping table is used to determine the value of the Content-Type response header and the format of the response payload.

Table: Accept Request Header to Content-Type Response Header Mapping

If the server cannot send a response that is acceptable, as indicated in the preceding Accept Request Header to Content-Type Response Header Mapping table and according to the Accept (section 2.2.5.1) header value, then, as specified in [RFC2616], the server SHOULD return a 4xx response.

The protocol defined in this document can be extended to support arbitrary message formats; however, the scope of this section is to define the use of the application/atom+xml (section 2.2.5.1.1) and application/json (section 2.2.5.1.2) formats. A data service MAY accept requests with Accept header values other than those shown in the table that follows. The returned Content-Type response header value for such requests is not defined by this specification.

2.2.5.1.1   application/atom+xml

This content type is used in a request to a data service to request the data service format the response payload using the application/atom+xml (section 2.2.5.1.1) format using the formatting rules outlined in AtomPub Format (section 2.2.6.2).

2.2.5.1.2   application/json

This content type is used in a request to a data service to request the data service format the response payload using the application/json (section 2.2.5.1.2) format according to the formatting rules outlines in JavaScript Object Notation (JSON) Format (section 2.2.6.3).

2.2.5.2   Content-Type

The Content-Type header is used as specified in [RFC2616]. However, because this document describes messages for the application/atom+xml, application/atom+xml, application/xml, text/plain, and text/xml  formats, a data service client or server SHOULD only use HTTP messages with a Content-Type header value as shown in the ABNF grammar that follows and is specified in [RFC5234]. The exception to the above rule is when messages are used that represent a Media Resource [RFC5023] or the raw value of an entity’s property (see section 2.2.3.5).

Listing: Content-Type Header ABNF Grammar

2.2.5.3   DataServiceVersion

This header is a custom HTTP header defined by this document for protocol versioning purposes.  This header MAY be present on any request or response message.

The syntax of the DataServiceVersion header is defined as follows:

Listing: DataServiceVersion Header ABNF Grammar

Example: DataServiceVersion: 1.0;AspNetAjax

If present on a request, the VersionNum section of the header value states the version of the protocol extensions defined in this document that the client used to generate the request, as specified in the preceding DataServiceVersion Header ABNF Grammar listing.

If present on a response, the VersionNum section of the header value states the version of the protocol extensions defined in this document that the server used to generate the response, as specified in the preceding DataServiceVersion Header ABNF Grammar listing.

For additional processing rules for this header, see Versioning and Capability Negotiation (section 1.7).

The VersionClientUserAgent section, as specified in the previous listing in this section, DataServiceVersion Header ABNF GrammarService Operation Parameters, of the header value is not significant, SHOULD NOT be interpreted by a data service, and SHOULD NOT affect the versioning semantics of a data service.

This document defines version 1.0 and 2.0 of the protocol extensions defined by this document.

2.2.5.4   ETag

An ETag (section 2.2.5.4) (entity tag) is an HTTP response header returned by an HTTP/1.1 compliant web server used to determine change in content of a resource at a given URL.  The value of the header is an opaque string representing the state of the resource at the time the response was generated.

The ETag header is used as specified in [RFC2616]. However, this document adds constraints to the header value to enable its use for optimistic concurrency control when performing operations that update entities on the server. Optimistic concurrency support is described in If-Match (section 2.2.5.5), If-None-Match (section 2.2.5.6), and ETag (section 2.2.5.4).

In the Entity Data Model associated with a service, some EntityTypes may have properties defined with a concurrencyMode, as specified in [MC-CSDL], whose value is "fixed". Such EntityTypes are considered enabled for optimistic concurrency control. For example, the Version property on the Customer EntityType defined in the model shown in Appendix A: Sample Entity Data Model and CSDL Document (section 6) defines the entire concurrency token of the type because no other properties on the type have the concurrencyMode facet.  If a base EntityType does not define a concurrency token, then that EntityType, and any of its subtypes, are not considered enabled for optimistic concurrency control.

When a server responds, indicating success, to a request performed against a URI that identifies a single entity, properties of an entity or a Media Resource (as specified in URI Format: Resource Addressing Rules (section 2.2.3),  and whose EntityType is enabled for optimistic concurrency control, it MUST include an ETag header in the HTTP response. The value of the header MUST represent the concurrency token for the entity that is identified by the request URI. The server MUST NOT include an ETag header in a response to any request performed against a URI that does not identify, as specified in URI Format: Resource Addressing Rules (section 2.2.3), a single entity, properties of an entity, or a Media Resource.  In addition, the server MUST NOT include an ETag header if the request URI identifies a single entity whose type is not enabled for optimistic concurrency control. Server response requests performed against URIs that do not return single entities MUST provide concurrency tokens in the response payload for any entities that are enabled for concurrency control.

For example, using the model in Appendix A: Sample Entity Data Model and CSDL Document, a valid URI identifying an EntityType instance is  http://host/service.svc/Customers('ALFKI').  As a counter example, the URIs  http://host/service.svc/Customers and http://host/service.svc/Customers('ALFKI')?$expand=Orders identify a collection of entities and thus MUST NOT include an ETag in a response associated with these request URIs.

A data service MAY<48> define concurrency tokens on the base EntityType associated with each EntitySet in the Entity Data Model used by the service.  Concurrency tokens are defined using the concurrencyMode facet, with a value of "fixed", on a property of an EntityType, as specified in [MC-CSDL].

An entity's concurrency token MUST be comprised of only Primitive type values (NavigationProperties and ComplexTypes cannot be annotated with the concurrencyMode facet and therefore cannot participate in the concurrency token for an EntityType), as specified in [MC-CSDL].  Because this document relies on the definition of concurrency tokens per [MC-CSDL], optimistic concurrency control is not defined for links or associations.  Therefore, a server MAY NOT perform optimistic concurrency control for operations that create or remove associations.  If a data service implementation is able to provide concurrency support on such operations without altering the rules in this section, it SHOULD do so.

Implementers of this document are recommended to order the property values that make up the concurrency token for an EntityType, and all of its sub types, using the same order of the properties listed in the metadata document of the data service.  RetrieveServiceMetadata Request (section 2.2.7.2.6) describes the Data Service Metadata document.

The syntax of the ETag header is defined as follows:

Example following the model defined in Appendix A: Sample Entity Data Model and CSDL Document:  ETag: W/"X'000000000000D2F3'"

2.2.5.5   If-Match

The If-Match request-header field is used with a method to make it conditional.  As specified in [RFC2616], "the purpose of this feature is to allow efficient updates of cached information with a minimum amount of transaction overhead.  It is also used, on updating requests, to prevent inadvertent modification of the wrong version of a resource".

The If-Match header is used in this document as specified in [RFC2616]; however, this document adds additional constraints to the types of requests for which the header may be provided.  Additional constraints are also added to the syntax of the header value.

This header MAY<49> only be present on GET, MERGE, or PUT requests to request URIs which identify the same Entity Data Model (EDM)  constructs as URI 2, URI 3, URI 4, URI 5 and URI 17 that are defined in Resource Path: Semantics (section 2.2.3.5).  Additionally, this header MAY<50> be present on DELETE requests to request URIs that identify the same EDM constructs as URI 2, as specified in Resource Path: Semantics (section 2.2.3.5), and any data service URI whose last path segment is "/$value".  This header MUST NOT be on any POST requests to a data service.

Client processing rules for this header are defined in Request Types (section 2.2.7) and server processing rules are in Message Processing Events and Sequencing Rules (section 3.2.5).

The syntax of the If-Match header is defined as follows:

Example: If-Match: W/"X'000000000000D2F3'"

2.2.5.6   If-None-Match

The If-None-Match request header is used with a method to make it conditional.  As specified in [RFC2616], "The purpose of this feature is to allow efficient updates of cached information with a minimum amount of transaction overhead. It is also used to prevent a method (for example, PUT) from inadvertently modifying an existing resource when the client believes that the resource does not exist."

The If-None-Match header is used in this document as specified in [RFC2616]. However, this document further limits it to the types of requests with which the header may be used.  Additional constraints are also added to the syntax of the header value.

This header MAY<51> be present only on GET , MERGE, or PUT requests to request URIs that identify the same Entity Data Model (EDM)  constructs as URI 2, URI 3, URI 4, URI 5, and URI 17, as defined in the Resource Path Semantics table in Resource Path: Semantics (section 2.2.3.5). Additionally, this header MAY<52> be used on DELETE requests to URIs which identify the same EDM constructs as URI 2, as specified in the table in Resource Path: Semantics (section 2.2.3.5), and any data service URI whose last path segment is "/$value".  This header MUST NOT be used on any POST requests to a data service.

Client processing rules for this header are defined in Request Types (section 2.2.7) and server processing rules are in Message Processing Events and Sequencing Rules (section 3.2.5).

The syntax of the If-None-Match header is defined as follows:

2.2.5.7   MaxDataServiceVersion

This header is a custom HTTP request only header defined by this document for protocol versioning purposes.  This header MAY be present on any request message from client to server.

If present on a request, the VersionNum section, as specified in the following ABNF grammar list, of the header value states the maximum version of the protocol extensions the client can accept in a response.

For additional processing rules for this header, see Versioning and Capability Negotiation (section 1.7).

The VersionServerUserAgent section, as specified in the following ABNF grammar list, of the header value is not significant, SHOULD NOT be interpreted by a  and SHOULD NOT affect the versioning semantics of a data service, see section data service.

The syntax of the MaxDataServiceVersion header is defined as follows:

Listing: Syntax of the MaxDataServiceVersion Header

2.2.5.8   X-HTTP-Method

This header is a custom HTTP request header defined by this document.

It is possible to instruct network intermediaries (proxies, firewalls, and so on) inspecting traffic at the application protocol (for example, HTTP) layer to block requests that contain certain HTTP verbs.  In practice, GET and POST verbs are rarely blocked (traditional web pages rely heavily on these HTTP methods), while, for a variety of reasons (security vulnerabilities in prior protocols, etc), other HTTP methods (HTTP PUT , HTTP DELETE, and so on) are at times blocked by intermediaries.  Additionally, some existing HTTP libraries do not allow creation of requests using verbs other than GET or POST.  Therefore, an alternative way of specifying request types which use verbs other than GET and POST is needed to ensure that this document works well in a wide range of environments.

To address this need, the X-HTTP-Method header can be added to a POST request that signals that the server MUST process the request not as a POST, but as if the HTTP verb specified as the value of the header was used as the method on the HTTP request's request line, as specified in [RFC2616] section 5.1).  This technique is often referred to as "verb tunneling".

This header is only valid when on HTTP POST requests.  A server MAY<53> support verb tunneling as defined in the preceding paragraph.  If a server implementing this document does not support verb tunneling, it MUST ignore a X-HTTP-Method header, if present in a POST request, and treat the request as a standard POST request.  This implies that a client of such a data service must determine in advance (using server documentation, and so on) if a given data service endpoint supports verb tunneling.  A tunneled request sent to a service that does not support verb tunneling will interpret the request as an insert request since HTTP POST requests map to an insert request, as specified in [RFC5023].

The syntax of the X-HTTP-Method is defined as follows:

For example, the HTTP request in the following Delete Request Tunneled in a POST Request listing instructs the server to delete the EntityType instance identified by EntityKey value 5 in the Categories EntitySet instead of performing an insert operation.

Listing: Delete Request Tunneled in a POST Request

2.2.6   Common Payload Syntax

The protocol extensions defined in this document enable clients and servers to perform actions (for example, CRUD operations) on entities in an Entity Data Model, as specified in [MC-CSDL], represented using one of multiple possible formats (AtomPub, JSON, and so on).  Each serialization format or representation of an entity may be used in the payload of request and response messages, as specified in Request Types (section 2.2.7).

The AtomPub Format (section 2.2.6.2) specifies how to represent Entity Data Model constructs (single EntityType instance, multiple EntityType instances in an EntitySet, NavigationProperties, and so on) using the AtomPub [RFC5023] format.

JavaScript Object Notation (JSON) Format (section 2.2.6.3) specifies how to represent Entity Data Model constructs (single EntityType instance, multiple EntityType instances in an EntitySet, NavigationProperties, and so on) using the JavaScript Object Notation (JSON) [RFC4627] format.

It should be noted that Request Types (section 2.2.7) defines additional payload syntax directives, dependent on the message context, that MUST be adhered to in addition to those outlined in this section.

2.2.6.1   Common Serialization Rules for XML-based Formats

AtomPub and custom XML formatted payloads representing EDM constructs, as specified in [MC-CSDL] and defined in AtomPub Format (section 2.2.6.2) and XML Format (section 2.2.6.5), consist of XML elements and attributes in the XML namespaces, as specified in [XMLNS], shown in the following Protocol Namespace Definitions table.  All XML elements and attributes associated with extensions to the Atom format defined in this document, as well as custom XML formats which hold data, are defined in the "Data Service" namespace.

All metadata related elements defined in this document are defined in the "Data Service Metadata" namespace.

Table: Protocol Namespace Definitions

XML payloads defined in this document may use the xml:base [XMLBASE] attribute, as specified in [RFC5023].  A data service and its client MUST understand and appropriately process this directive.

All EDM Primitive types represented as XML element values MUST be formatted as defined by the rules in the following EDM Primitive Type Formats for Element Values table.  In addition to the rules stated in the table, if the value of a Primitive type is null, then the value of the associated XML element MUST be empty.  In addition, an m:null attribute with value set to 'true' MUST be present on the containing element.

Table: EDM Primitive Type Formats for XML Element Values

2.2.6.2   AtomPub Format

Atom is an XML-based document format described in [RFC4287] and extended with AtomPub specific extensions in [RFC5023].  This section uses the term AtomPub as shorthand to refer to the union of the document format rules defined in [RFC4287] and [RFC5023].

AtomPub describes lists of related information (a collection in the abstract AtomPub Protocol Model [RFC5023] section 4.2) known as "feeds".  Feeds are composed of a number of items, known as "entries" (Entry Resources in the abstract AtomPub Protocol Model [RFC5023] section 4.2), each with an extensible set of attached metadata.  For example, each entry MUST have a title.

The following subsections define the mapping of constructs in the Entity Data Model to <Atom format> elements for use in request/response messages as specified in Request Types (section 2.2.7).  In all subsections below, if a data model construct is not explicitly described then an associated Atom-based representation is not defined by this document. For such constructs, servers and clients MAY<54> either:

§ Define their own representations and include them in a request or response if valid as per [RFC5023].

§ Exclude them from requests and responses.

The examples in this section use the sample data model defined in Appendix A: Sample Entity Data Model and CSDL Document (section 6) .

2.2.6.2.1   Entity Set (as an Atom Feed Element)

An EntitySet or collection of entities MUST be represented as an <atom:feed> element, as specified in [RFC4287] section 4.1.1.  This section adds constraints to the formatting rules defined in AtomPub for <atom:feed> elements.

An Atom-formatted EntitySet or collection of entities MUST adhere to the rules defined in this section.

<atom:feed> Element

This element is specified in [RFC4287] section 4.1.1

<atom:feed> Sub Elements

The <atom:id> element, as specified in [RFC4287] section 4.2.6, MUST contain the URI that identifies the EntitySet represented by the parent <atom:feed> element.  For example, assuming the parent element represented the Customers EntitySet (as described in Appendix A: Sample Entity Data Model and CSDL Document (section 6)) the value of this element would be http://host/service.svc/Customers.

The <atom:title> element, as specified in [RFC4287] section 4.2.14, MAY contain the name of the EntitySet represented by the parent <atom:feed> element.  The set name MAY be qualified with the name of the EDM namespace in which it is defined, as specified in see [MC-CSDL].  If the URI in the sibling <atom:id> element is of the same form as URI 6, as defined in Resource Path: Semantics (section 2.2.3.5) (last path segment is a NavigationProperty) and the NavigationProperty identifies an EntitySet, then the <atom:title> element MAY contain the name of the NavigationProperty instead of the name of the EntitySet identified by the property.

An <atom:link> element, as specified in [RFC4287] section 4.2.7, with a rel="self" attribute MUST contain an href attribute with value equal to the URI used to identify the set that the parent <atom:feed> element represents.  When used in HTTP responses, this URI MUST be equal to the associated HTTP request URI.  When used in HTTP deep insert requests, this URI MUST identify a related collection of entities (identified by a NavigationProperty on the base EntityType of the EntitySet identified by the request URI) into which the deep/related new entities will be inserted, as specified in InsertEntity Request (section 2.2.7.1.1).

<atom:entry> elements, as specified in [RFC4287] section 4.1.2, within the <atom:feed> element, are formatted as specified in Entity Type (as an Atom Entry Element) (section 2.2.6.2.2).

In response payloads only, if the server does not include an <atom:entry> element as a child element of the <atom:feed> element for every entity in the collection of entities identified by the associated URI, then the <atom:feed> element represents a partial collection as defined in AtomPub [RFC5023] section 10.1.  The href attribute of the <atom:link rel="next"> element mandated by AtomPub [RFC5023] section 10.1 for such partial representations MUST have a value equal to the URI that identifies the next partial set of entities from the originally identified complete set.  Such a URI SHOULD include a Skip Token System Query Option (section 2.2.3.6.1.9) to indicate the URI addresses the next (after the partial set represented by the parent <atom:feed> element) partial set of entities.

Implementers of this protocol should note that the inclusion of an <atom:link rel="next"> element in a response payload has protocol versioning implications as described in Executing a Received RetrieveValue Request (section 3.2.5.4.2).

2.2.6.2.1.1   Inlinecount Representation (for collections of entities)

This section defines an extended representation of a collection of entities from that described in section 2.2.6.2.1. This representation is only supported in version 2.0 of the extensions defined by this specification to the AtomPub protocol.

A request URI MAY contain an $inlinecount System Query Option to indicate that the count of the number of entities represented by the query after filters have been applied and before applying any other query option processing MUST be included in the result sent by the data service.

The count value included in the result MUST be enclosed in an <m:count> element. The <m:count> element MUST be a direct child element of the <feed> element and MUST occur before any <atom:entry> elements in the feed.

For example, the count of all Customer Entities using the Customer EntityType instance described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) is represented in Atom as described in the following feed. In the example, the request included the Inlinecount System Query Option and the Top System Query Option with a value of 1.

2.2.6.2.2   Entity Type (as an Atom Entry Element)

An EntityType instance MUST be represented as an <atom:entry> element, as specified in [RFC4287] (section 4.1.2).  This section adds additional constraints to the formatting rules defined in Atom for <atom:entry> elements.

An Atom-formatted EntityType instance MUST adhere to the rules defined in this section.

atom:entry Element: This element is specified in [RFC4287] section 4.1.2

atom:entry Sub Elements: If the entity represents an AtomPub Entry Resource [RFC5023] (section 4.2), the <atom:content> element MUST contain a "type" attribute with the value "application/xml".  The <atom:content> element MUST also contain one <m:properties> child element. The <m:properties> element MUST contain one child element for each EDMSimpleType and ComplexType property of the EntityType instance represented by the <atom:entry> element that is not otherwise mapped through a Customizable Feed property mapping in its Data Service Metadata Document (as defined in section 2.2.3.7.2.1). If the Entity Type instance being represented was identified with a URI that includes a Select System Query Option (section 2.2.3.6.1.11), then the prior rule is relaxed such that only the properties identified by the $select query option SHOULD be represented as child elements of the <m:properties> element. Each child element representing a property MUST be defined in the data service namespace, as described in Common Serialization Rules for XML-based Formats (section 2.2.6.1), and the element name must be the same as the property it represents. Rules for representing an Entity Type as an <atom:entry> element with Customizable Feed property mappings defined are defined in Entity Type (as an Atom Entry Element) with a Customizable Feed Property Mapping (section 2.2.6.2.2.1).

If the entity represents an AtomPub Media Link Entry, as specified in [RFC5023] (section 4.2), the <m:properties> element MUST also contain the EDMSimpleType and ComplexType properties of the EntityType instance, represented as described by the preceding paragraph; however, the  <m:properties> element MUST be a direct child of the <atom:entry> element (as opposed to the <atom:content> element). Additionally, as specified in [RFC5023], an <atom:link> element SHOULD be included, which contains an atom:rel="edit-media". If such an <atom:link> element identifies a Media Resource with an associated concurrency token, then the element SHOULD include an m:etag attribute with a value equal to the ETag of the Media Resource identified by the <atom:link> element.

An <atom:category> element containing an <atom:term> and atom:scheme attribute MUST be included if the EntityType of the EntityType instance represented by the <atom:entry> object is part of an inheritance hierarchy, as described in [MC-CSDL] (section 1). If the EntityType is not part of an inheritance hierarchy, then the <atom:category> element MAY be included. The value of the atom:term attribute MUST be the namespace qualified name of the EntityType of the instance represented by the <atom:entry> element. The value of the atom:scheme attribute MUST be a data service specific IRI which, as specified in [RFC4287], identifies the categorization scheme used. If a data service does not have a scheme IRI, it SHOULD use the URI shown in grammar rule dataServiceSchemeURI in the Entity Type Atom Representation URIs (ABNF Grammar) listing that follows in this section.

An m:etag attribute MAY be included on the <entry> element representing the EntityType instance.  In this context, the "m" prefix refers to the Data Service Metadata namespace defined in Common Serialization Rules for XML-based Formats (section 2.2.6.1).  When included, it MUST represent the concurrency token associated with the EntityType instance, as defined in ETag (section 2.2.5.4), and MUST be used instead of the ETag HTTP Header defined in ETag (section 2.2.5.4), which, as per [RFC2616], is used to represent a single entity)  when multiple entities are present in a single payload.

An <atom:link> element SHOULD be included, which contains an atom:rel="edit" or atom:rel="self" attribute. The atom:rel attribute MAY<55> be used to indicate that a resource is read-only (when the value of the attribute is "self") or read-write (when the attribute's value is  "edit"). If such an <atom:link> element is included, it MUST have an atom:href attribute whose value is a URI that identifies the entity represented by the <atom:entry> element.

In responses to retrieve requests, as specified in RetrieveEntity Request (section 2.2.7.2.2), servers MUST represent each NavigationProperty of the EntityType as an <atom:link> element that is a child element of the <atom:entry> element. Each <atom:link> element MUST contain an atom:rel attribute with the value defined by the relNavigationlLinkURI rule shown in the following grammar, as defined in the listing that follows. The element SHOULD also contain an atom:title attribute with the value equal to the NavigationProperty name and MUST contain an atom:href attribute with value equal to the URI which identifies the NavigationProperty on the EntityType. Implementers should note that Atom also requires an atom:type attribute, which should have a value of application/atom+xml;type=entry when the NavigationProperty identifies a single entity instance and application/atom+xml;type=feed when the property identifies an EntitySet.

Listing: Entity Type Atom Representation URIs (ABNF Grammar)

For example, the Customer EntityType instance described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) is represented in Atom as described in the following listing.

Listing: Atom-formatted Customer Entity

2.2.6.2.2.1   Entity Type (as an Atom Entry Element) with a Customizable Feed Property Mapping

If the Entity Type instance represented includes Customizable Feeds annotations in the data services metadata document, then the properties with custom mappings must be represented as directed by the mappings information specified in Conceptual Schema Definition Language Document for Version 2.0 Data Services (section 2.2.3.7.2.1). Properties that do not have Customizable Feeds mappings defined are represented as per the prior section, Entity Type (as an Atom Entry Element) (section 2.2.6.2.2).

If the property of an Entity Type instance in a Data Service response includes Customizable Feeds annotations in the data services metadata document and has a value of null, then the element or attribute being mapped to MAY be present and MUST be empty.

For example, the Employee Entity Type instance described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) is represented in Atom as described in the following listing.

Listing: Atom-formatted Customer Entity with a Property Mapping

2.2.6.2.3   Complex Type

A ComplexType property on an EntityType MUST be serialized within the <m:properties> element of an <atom:content> element or <atom:entry> element, as specified in  Entity Type (as an Atom Entry Element) (section 2.2.6.2.2).

Each declared property defined on a ComplexType MUST be represented as a child element (in the data service namespace defined in Common Serialization Rules for XML-based Formats (section 2.2.6.1) of the element representing the ComplexType as a whole.

An Atom representation of a ComplexType outside of the context of an <atom:entry> element as described in the preceding paragraph is not defined by this document.  See  Complex Type (section 2.2.6.5.1) for details regarding formatting a ComplexType using XML independent from the content of the defining EntityType.

2.2.6.2.4   Navigation Property

See the description of the <atom:link> element in Entity Type (as an Atom Entry Element) (section 2.2.6.2.2) and Deferred Content (section 2.2.6.2.6) that follows.

2.2.6.2.5   EDMSimpleType Property

For a description of how properties are serialized in request/response payloads representing an EntityType instance, see Entity Type (as an Atom Entry Element) (section 2.2.6.2.2).

An Atom representation of properties outside of the context of an <atom:entry> element is not defined.  See EDMSimpleType Property (section 2.2.6.5.3)  for details regarding formatting an EDMSimpleType property using XML independent from the content of the defining EntityType.

2.2.6.2.6   Deferred Content

The serialized representation of an entity and its related entities, identified by NavigationProperties, may be large.  For resource conservation purposes (bandwidth, CPU, and so on) a data service will generally not want to return the full graph of entities related to the EntityType instance or set identified in a request URI.  For example, a data service SHOULD defer sending entities represented by any navigation property in a response unless explicitly asked to send those entities via the $expand System Query Option, as described in Expand System Query Option ($expand) (section 2.2.3.6.1.3).

Entity Type (as an Atom Entry Element) (section 2.2.6.2.2) specifies Atom-formatted EntityType instances which MUST contain <atom:link> elements for each NavigationProperty on the EntityType. When these <atom:link> elements are empty, they signify deferred NavigationProperty content (for example, the entities represented by the NavigationProperty are not serialized inline).  For example, using the two EntityTypes Customer and Order, as specified in Appendix A: Sample Entity Data Model and CSDL Document (section 6), the default Atom serialization of the Customer instance with EntityKey value of 'ALFKI' is shown with deferred NavigationProperty content in the Atom formatted Customer Entity listing in Entity Type (as an Atom Entry Element) (section 2.2.6.2.2).

In the example, the presence of the empty <atom:link> element with 'rel' attribute whose value is http://schemas.microsoft.com/ado/2007/08/dataservices/related/Orders signifies that the value of the Orders NavigationProperty is deferred (this is not directly represented in this serialization). In order to retrieve the deferred value(s), a client can make a separate request to the navigation property URIservice.svc/Customers('ALFKI')/Orders or explicitly ask that the property be loaded inline via the $expand System Query Option, as described in Expand System Query Option ($expand) (section 2.2.3.6.1.3).

2.2.6.2.6.1   Inline Representation

A request URI may include the $expand System Query Option to explicitly request that the entity or  entities represented by a NavigationProperties property be serialized inline (rather than deferred), as described in Expand System Query Option ($expand) (section 2.2.3.6.1.3). The example that follows uses the same data model as the Deferred Content example referenced previously; however, this example shows the value of the Orders NavigationProperty serialized inline.

A NavigationProperty that represents an EntityType instance or a group of entities and that is serialized inline MUST be placed within a single <m:inline> element that is a child element of the <atom:link> element representing the NavigationProperty.  Since a NavigationProperty identifies a collection of entities or a single entity, the contents of the <m:inline> element will be described in Entity Set (as an Atom Feed Element) (section 2.2.6.2.1) or Entity Type (as an Atom Entry Element) (section 2.2.6.2.2).  If the value of a NavigationProperty is null, then an empty <m:inline> element MUST appear under the <atom:link> element which represents the Navigation property, indicating that the element has been expanded but that there was no content associated with it.

Listing: Atom-formatted Customer Entity with the Orders Navigation Property Value Formatted Inline

2.2.6.2.7   Service Document

Service Document (section 2.2.3.7.1) specifies that AtomPub, as specified in [RFC5023], defines a Service Document which describes collections of resources available from a data service.  The root URL of a data service that implements the protocol defined in this document SHOULD identify such a service document.  In this service document, a data service SHOULD represent all available collections in a single <app:workspace> element.  See [RFC5023] section 8.3.2 for the definition of the <app:workspace> element and [RFC5023] section 6.1 for the definition of the 'app' prefix.  Within that workspace, a data service MUST represent each EntitySet in its associated Entity Data Model, as described in Abstract Data Model (section 2.2.1), as an <app:collection> element, as specified in [RFC5023] section 8.3.3.  The URI identifying the EntitySet MUST be used as the value of the 'href' attribute of the <app:collection> element.  The name of the EntitySet MAY be used as the value of the <atom:title> element which, as specified in [RFC5023], is a mandatory child element of the <app:collection> element.

The following is an example AtomPub Service Document, as specified in [RFC5023], for the Entity Data Model described in Appendix A: Sample Entity Data Model and CSDL Document (section 6).

Listing: AtomPub Service Document Describing a Data Service

2.2.6.2.8   Additional Representations

In AtomPub, as specified in [RFC5023], the structured unit of information is an Entry Resource that is represented as an <atom:entry> element and, as specified in Entity Type (as an Atom Entry Element) (section 2.2.6.2.2), is used to represent EntityTypes. A standalone Atom-based representation of the constituent EDM constructs of an EDMSimpleType property is not defined by this document.

The URI-addressing scheme for data services, as defined in URI Format: Resource Addressing Rules (section 2.2.3), does enable addressing the constituent EDM constructs of an EntityType directly. For XML and JSON serialization rules for such resources, see XML Format (section 2.2.6.5) and JavaScript Object Notation (JSON) Format (section 2.2.6.3).

2.2.6.3   JavaScript Object Notation (JSON) Format

JavaScript Object Notation (JSON) is a lightweight data interchange format based on a subset of the JavaScript Programming Language standard, as specified in [ECMA-262].  JSON is a text format that is language independent, but uses conventions that are familiar to programmers of the C-family of languages (C, C++, JavaScript, and so on).  Data serialized using JSON can easily be turned into JavaScript objects for programmatic manipulation. JSON notation consists of two structures: a JSON Object (collection of name/value pairs) and a JSON Array (an ordered list of values).

The following subsections define the mapping between Entity Data Model constructs and their serialized representations in the JSON, as specified in [RFC4627], for use in request/response messages, as specified in Request Types (section 2.2.7).

In all subsections below, if a data model construct is not explicitly referenced, then an associated JSON representation is not defined by this document.

2.2.6.3.1   Common JSON Serialization Rules for All EDM Constructs

Literal values of the EDM Primitive types are represented as JSON literal values, as defined by the rules in the following Common JSON Serialization Rules for All EDM Constructs table.  Grammar rules not defined here are specified in [RFC5234] and/or [RFC4627].

Table: Common JSON Serialization Rules for All EDM Constructs

2.2.6.3.2   Entity Set (as a JSON array)

An EntitySet or collection of entities MUST be represented as an array of JSON objects, with one object for each EntityType instance within the set.  A JSON-based format for EntityTypes is defined in Entity Type (as a JSON object) (section 2.2.6.3.3).

An empty EntitySet or collection of entities (one that contains no EntityType instances) MUST be represented as an empty JSON array.

The syntax of version 1.0 and version 2.0 compliant JSON representations of a collection of entities is defined by the grammar listed in this section. The grammar rule 'entitySetInJson' defines the version 1.0 JSON representation of a collection of entities that may be used in both request and response payloads. The grammar rule 'entitySetInJson2' defines the version 2.0 JSON representation of a collection of entities for response payloads only. No version 2.0 format for use in request payloads is defined by this specification.

Listing: Entity Set JSON Representation

In response payloads representing a collection of entities, if the server does not include an entityTypeInJson name value pair (see section 2.2.6.3.3) for every entity in the collection of entities identified by the associated URI, then the JSON array represents a partial collection of entities.  In this case, a nextLinkNVP name value pair MUST be included in the JSON array to indicate it represents a partial collection.  The URI in the associated nextURINVP name value pair MUST have a value equal to the URI, which identifies the next partial set of entities from the originally identified complete set.  Such a URI SHOULD include a Skip Token System Query Option (section 2.2.3.6.1.9) to indicate that the URI addresses the subsequent partial set of entities.

Implementers of this protocol should note that the inclusion of a nextLinkNVP name value pair in a JSON representation of a collection of entities has protocol versioning implications as described in Executing a Received RetrieveValue Request (section 3.2.5.4.2).

2.2.6.3.2.1   Inlinecount Representation (for collections of entities)

This section defines the semantics of the "countNVP" grammar rule in section 2.2.6.3.2, which is only supported in version 2.0 of the extensions defined by this specification to the AtomPub protocol.

A request URI MAY contain an $inlinecount System Query Option to indicate that the count of the number of entities represented by the query after filters have been applied should be included in the collection of entities returned from a data service. If such a query string object is present, the response MUST include the countNVP name/value pair (before the results name/value pair) with the value of the name/value pair equal to the count of the total number of entities addressed by the request URI.

For example, the count of all Customer Entities using the Customer EntityType instance described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) is represented in JSON as shown in the following sample response payload. This example assumes the request URI includes the Inlinecount System Query Option and the Top System Query Option with a value of 1.

2.2.6.3.3   Entity Type (as a JSON object)

An instance of an EntityType MUST be serialized as a JSON object.

Each property on the EntityType MUST be represented as a name/value pair, as specified in [RFC4627], within the object. Alternatively, if the Entity Type instance being represented is identified with a URI that includes a Select System Query Option (section 2.2.3.6.1.11), then the prior rule is relaxed such that only the properties identified by the $select query option MUST be represented by name/value pairs. The name in the name/value pair is the name of the property as defined on the EntityType, and the value of the pair is the value of the property.  The order name/value pairs that appear within a JSON object MUST be considered insignificant.  Name/value pairs not representing a property defined on the EntityType SHOULD NOT be included.  The sub-sections below describe additional formatting rules for each type of property defined on an EntityType.

The JavaScript Object Notation (JSON) serialization of an EntityType instance MAY<56> include a name/value pair named '__metadata'.  This name/value pair is not data, but instead, by convention defined in this document, specifies the metadata for the EntityType instance that the JSON object represents.  The value of the '__metadata' property contains seven name/value pairs: 'uri', 'type,' 'etag', 'edit_media', 'media_src', 'media_etag', and 'content_type'.  The order of these name/value pairs is insignificant.  The value of the 'uri' name/value pair MUST be the canonical URI identifying the EntityType instance represented by the JSON object.

The 'type' name/value pair MUST be included if the EntityType of the EntityType instance represented by the JSON object is part of an inheritance hierarchy, as described in [MC-CSDL] (section 1).  If the EntityType is not part of an inheritance hierarchy, then the 'type' name/value pair MAY be included. The value of the 'type' name/value pair MUST be the namespace qualified name, as specified in [MC-CSDL], of the EntityType of the instance that the JSON object represents.

The 'etag' name/value pair MAY be included.  When included, it MUST represent the concurrency token associated with the EntityType instance ETag (section 2.2.5.4) and MUST be used instead of the ETag HTTP Header defined in ETag (section 2.2.5.4), which, as specified in [RFC2616], is used to represent a single entity when multiple entities are present in a single payload.

The 'media_src' and 'content_type' name/value pairs MUST be included and the 'edit_media' and 'media_etag' name/value pairs MAY be included if the entity being represented is a Media Link Entry (for example, the description of the Entity Type as shown in the data services’ conceptual schema definition language document includes the HasStream='true' attribute as defined in section 2.2.3.7.2.  If the entity being represented is not a Media Link Entry, then the 'edit_media', 'media_src', 'media_etag', and 'content_type' name/value pairs MUST NOT be included.

The value of the 'edit_media' name/value pair MUST be a URI that is equivalent to the value of the 'href' attribute on a <atom:link rel="edit-media"> AtomPub element if the entity was to be represented the AtomPub [RFC5023] format, instead of JSON.  The value of the 'media_src' name/value pair MUST be a URI that is equivalent to the value of the 'src' attribute on the <atom:content> AtomPub element if the entity was to be represented using the AtomPub [RFC5023] format, instead of JSON. The value of the 'content_type' name/value pair MUST be equivalent to the value of the 'type' attribute on the <atom:content> AtomPub element if the entity was to be represented using the AtomPub [RFC5023] format, instead of JSON. The value of the 'media_etag' name/value pair MUST be equal to the value of the concurrency token associated with the Media Resource identified by the 'edit_media' and/or 'media_src' name/value pairs.

The JSON object representing the EntityType SHOULD also contain representations of the properties defined on the EntityType.  Each EDMSimpleType, ComplexType, and NavigationProperty defined on the EntityType MUST be formatted as per the directives in sections EDMSimpleType Property (section 2.2.6.3.8), Complex Type (section 2.2.6.3.4), and Navigation Property (section 2.2.6.3.6).

The syntax of version 1.0 and version 2.0 compliant JSON representations of an entity is defined by the grammar listed in this section. The grammar rule 'entityTypeInJson' defines the version 1.0 JSON representation of an entity that can be used in both request and response payloads. The grammar rule 'entityTypeInJson2' defines the version 2.0 JSON representation of an entity for response payloads only. This specification does not define a version 2.0 JSON representation of an entity for use in request payloads.

Listing: Entity Type JSON Representation

For example, the Customer EntityType instance described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) is represented in JSON, as shown in the following listing.

Listing: JSON-formatted Customer Entity

2.2.6.3.4   Complex Type

An instance of a ComplexType MUST be represented as a JSON object.  Each declared property defined on the ComplexType MUST be represented as a name/value pair within the JSON object.  Additional name/value pairs that do not represent a declared property of the ComplexType SHOULD NOT be included.  The name in the name/value pair MUST equal the name of the declared property on the ComplexType and the value of the pair MUST equal the value of the property.  The order name/value pairs that appear within the JSON object MUST be considered insignificant.

The syntax of version 1.0 and version 2.0 compliant JSON representations of a ComplexType is defined by the grammar listed in this section. The grammar rule 'entityCTInJson' defines the version 1.0 JSON representation of a ComplexType that can be used in both request and response payloads. The grammar rule 'entityCTInJson2' defines the version 2.0 JSON representation of a ComplexType for response payloads only. This specification does not define a version 2.0 JSON representation of an entity for use in request payloads.

Listing: Complex Type JSON Representation

2.2.6.3.5   Collection of Complex Type Instances

A collection of ComplexType instances MUST be represented as an array of JSON objects.  Each object in the array represents a single ComplexType instance as specified in section 2.2.6.3.4.

The syntax of version 1.0 and version 2.0 compliant JSON representations of a collection of ComplexType instances is defined by the grammar listed in this section. The grammar rule 'entityCollCTInJson' defines the version 1.0 JSON representation of a collection of ComplexType instances that can be used in both request and response payloads. The grammar rule 'entityCollCTInJson2' defines the version 2.0 JSON representation of a collection of ComplexType instances for response payloads only. This specification does not define a version 2.0 JSON representation of a collection of ComplexType instances for use in request payloads.

2.2.6.3.6   Navigation Property

The default representation of a NavigationProperty is as a JSON name/value pair.  The name is equal to '__deferred' and the value is a JSON object that contains a single name/value pair with the name equal to 'uri'.  The value of the 'uri' name/value pair MUST be a URI relative to the Service Root URI, as specified in Service Root (section 2.2.3.2), that identifies the NavigationProperty.

The syntax of a NavigationProperty, represented within a JSON object, is shown using the grammar rule 'deferredNavProperty' in the Entity Type JSON Representation listing in  Entity Type (as a JSON object (section 2.2.6.3.3).

2.2.6.3.7   Collection of EDMSimpleType Values

A collection of EDMSimpleType values MUST be represented as an array of JSON primitives.  Each element in the array represents a single Primitive type value.

The syntax of version 1.0 and version 2.0 compliant JSON representations of a collection of EDMSimpleType values is defined by the grammar listed in this section. The grammar rule 'entityCollPrimValueInJson' defines the version 1.0 JSON representation of a collection of EDMSimpleType values that can be used in both request and response payloads. The grammar rule 'entityCollPrimValueInJson2' defines the version 2.0 JSON representation of a collection of EDMSimpleType values for response payloads only. This specification does not define a version 2.0 JSON representation of a collection of EDMSimpleType values for use in request payloads.

2.2.6.3.8   EDMSimpleType Property

A property of type EDMSimpleType MUST be represented as a JSON name/value pair.  The name in the name/value pair MUST be equal to the name of the EDM property and the value must be set to the value of the property.  The value MUST be formatted, as specified in Common JSON Serialization Rules for All EDM Constructs (section 2.2.6.3.1).

When represented as part of the JSON representation of an EntityType or ComplexType, the syntax of an EDMSimpleType Property formatted in JSON is as follows.

When represented as a standalone construct, the syntax of version 1.0 and version 2.0 compliant JSON representations of an EDMSimpleType is defined by the grammar listed as follows. The grammar rule 'entityPropertyInJson' defines the version 1.0 JSON representation of property that can be used in both request and response payloads. The grammar rule 'entityPropertyInJson2' defines the version 2.0 JSON representation of a property for response payloads only. This specification does not define a version 2.0 JSON representation of a property for use in request payloads.

2.2.6.3.9   Deferred Content

The serialized representation of an entity and its related entities, identified by NavigationProperties, may be large.  To conserve resources (bandwidth, CPU, and so on), it is generally not a good idea for a data service to return the full graph of entities related to the EntityType instance or set identified in a request URI.  For example, a data service SHOULD defer sending entities represented by any navigation property in a response unless explicitly asked to send those entities via the $expand System Query Option, as described in Expand System Query Option ($expand) (section 2.2.3.6.1.3).

In JSON-formatted EntityType instances (Entity Type (as a JSON object) (section 2.2.6.3.3)), NavigationProperties serialized as name/value pairs in which the value is a JSON object containing a single name/value pair with the name '__deferred' and a value equal to the URI that can be used to retrieve the deferred content, signify deferred NavigationProperty content (for example, the entities represented by the NavigationProperty are not serialized inline).  For example, using the two EntityTypes Customer and Order, as described in Appendix A: Sample Entity Data Model and CSDL Document (section 6), the default JSON serialization (with deferred NavigationProperty content) of the Customer instance with EntityKey value of 'ALFKI' is shown in Entity Type (as a JSON object) (section 2.2.6.3.3).

In the example, the presence of the '__deferred' name/value pair signifies that the value of the Orders Navigation Property is not directly represented on the JSON object in this serialization. In order to obtain the deferred value(s), a client would make a separate request directly to the navigation property URI (service.svc/Customers('ALFKI')/Orders) or explicitly ask that the property be serialized inline via the $expand System Query Option, as described in Expand System Query Option ($expand) (section 2.2.3.6.1.3) .

2.2.6.3.9.1   Inline Representation

As described in Expand System Query Option ($expand) (section 2.2.3.6.1.3), a request URI may include the $expand System Query Option to explicitly request the entity or entities represented by a NavigationProperties property be serialized inline, rather than deferred.  The example below uses the same data model as the Deferred Content example referenced above; however, this example shows the value of the Orders NavigationProperty serialized inline.

A NavigationProperty which is serialized inline MUST be represented as a name/value pair on the JSON object with the name equal to the NavigationProperty name.  If the NavigationProperty identifies a single EntityType instance, the value MUST be a JSON object representation of that EntityType instance, as specified in Entity Type (as a JSON object) (section 2.2.6.3.3).  If the NavigationProperty represents an EntitySet, the value MUST be as specified in Entity Set (as a JSON array) (section 2.2.6.3.2).

Version 1.0 JSON-formatted Customer Entity with the Orders Navigation Property Value Formatted Inline

2.2.6.3.10   Links

Links represent unidirectional associations or one direction of a bidirectional association between EntityType instances.  In the JSON format, Links are serialized as an array  of URIs, each of which identifies a single linked entity.

When represented in JSON, Links MUST be formatted, as shown in the table in the following listing, ABNF Grammar for Links Represented in JSON, using one JSON object containing a single 'uri' name/value pair per Link.  The value of the 'uri' name/value pair on each object MUST equal the absolute, canonical URI representing the linked-to EntityType instance.

The syntax of version 1.0 and version 2.0 compliant JSON representations of a collection of links is defined by the grammar listed in this section. The grammar rule 'linkCollJson' defines the version 1.0 JSOn representation of a collection of links that can be used in both request and response payloads. The grammar rule 'linkCollJson2' defines the version 2.0 JSON representation of a collection of links for response payloads only. This specification does not define a version 2.0 JSON representation of a collection of links for use in request payloads.

Listing: ABNF Grammar for Links Represented in JSON

For example, using the sample model and instance data, as described in Appendix A: Sample Entity Data Model and CSDL Document (section 6)), the Links from the Customer with EntityKey 'ALFKI' to Order instances is represented as shown in the following Example of Links Formatted using JSON listing. Each URI in the array identifies a single Order that is associated with the Customer.

Listing: Example of Links Formatted using Version 1.0 JSON Representation

2.2.6.3.11   Inlinecount Representation (collections of Links)

This section defines the semantics of the 'countNVP' grammar rule in section 2.2.6.3.10, which is only supported in version 2.0 of the extensions defined by this specification to the AtomPub protocol.

A request URI MAY contain an $inlinecount System Query Option to indicate that the count of the number of links represented by the query should be included in the collection of links returned from the data service. If such a query string token is present, the response MUST include the countNVP name/value pair (before any linkURINVP name/value pairs) with the value of the name/value pair equal to the count of the total number of links addressed by the request URI.

2.2.6.3.12   Service Document

Service Document (section 2.2.3.7.1) specifies that AtomPub, as specified in [RFC5023], defines a Service Document which describes collections of resources available from a data service.  The root URL of a data service that implements the protocol defined in this document MUST identify such a service document.  This section defines a JSON, as specified in [RFC4627], representation of the data provided in an AtomPub, as specified in [RFC5023] Service Document.  For a description of the contents of a Service Document for which this section defines a JSON serialization, see Service Document (section 2.2.3.7.1).

The syntax of a JSON-serialized Service Document is as shown in the grammar that follows.

The following is an example JSON, as specified in [RFC4627], representation of the information provided by an AtomPub, as specified in [RFC5023], Service Document for the Entity Data Model described in Appendix A: Sample Entity Data Model and CSDL Document (section 6).

Listing: JSON Service Document Describing a Data Service

2.2.6.4   Raw Format

The data service URI addressing scheme, as specified in URI Format: Resource Addressing Rules (section 2.2.3), enables directly addressing the "raw" value (see URI 4 and URI 5 in Resource Path: Semantics (section 2.2.3.5)) of EDMSimpleType properties defined on an EntityType or ComplexType. This allows the constituent parts of an EntityType to be identified independent of the rest of the EntityType and without any wrapping syntax.

2.2.6.4.1   EDMSimpleType Property

By default, the raw value (identified via URIs with Resource Paths ending in "$value") of any EDMSimpleType property (except those of type Edm.Binary) SHOULD be represented using the text/plain media type and MUST be serialized as specified in Common Serialization Rules for XML-based Formats (section 2.2.6.1).  A data service MAY<57> customize the media type used for any property.   The raw value of an Edm.Binary property MUST be an unencoded byte stream.

If the value of the property to be serialized is null, see Common Serialization Rules for XML-based Formats (section 2.2.6.1), because the representation is format specific.

2.2.6.5   XML Format

The data service URI addressing scheme, specified in URI Format: Resource Addressing Rules (section 2.2.3), enables the constituent parts of an EntityType and associations between EntityTypes to be identified directly.  This allows interaction with a specific piece of data or relationship, independent of the rest of the EntityType. Servers responding to requests identifying a constituent part of an EntityType instance MUST respond with an XML-based serialization of that part's value, as specified in this section, unless the request URI's Resource Path ends in $value (in which case it should use the format defined in Raw Format (section 2.2.6.4).

The serializations defined in the following subsections MUST be identified with the application/xml media type or text/xml media types.

2.2.6.5.1   Complex Type

A ComplexType property, defined on an EntityType, MUST be represented in the same way as it is within in the Atom-based format, as specified in section Complex Type (section 2.2.6.2.3); however, the XML element representing the ComplexType instance as a whole MUST be the root of the XML document (for example, not a child element, as described in section Complex Type (section 2.2.6.2.3) ). For example, the Address property of type CAddress (a ComplexType) in the sample model (see Appendix A: Sample Entity Data Model and CSDL Document (section 6)) is represented in the following listing.

If the value of the ComplexType is null, then there does not exist a serialization of the property's value in this form.  In such cases, it is left to the protocol's interaction model to signal such values, as described in Message Processing Events and Sequencing Rules (section 3.2.5) .

Listing: XML-formatted Complex Type

2.2.6.5.2   Collection of Complex Type Instances

A collection of ComplexType instances MUST be represented in XML as a single XML document with the root element of the document equal to the same name of the Service Operation returning the ComplexType instances.  The root element and all its child elements MUST exist in the Data Service Metadata namespace, as specified in Common Serialization Rules for XML-based Formats (section 2.2.6.1).

Each ComplexType instance in the collection must be represented as a child element of the root element and be named 'element'.  An attribute named 'type' (in the Data Service Metadata namespace, as described in Common Serialization Rules for XML-based Formats (section 2.2.6.1), MUST exist on the element.  The value of this attribute MUST specify the namespace qualified type name of the ComplexType.

Each property of the ComplexType instance MUST be represented in the same way as in the XML serialization of a single ComplexType, as described in Complex Type (section 2.2.6.2.3).

2.2.6.5.3   EDMSimpleType Property

Properties of type EDMSimpleType MUST be represented as a single (root) XML element in the data service namespace, as described in Common Serialization Rules for XML-based Formats (section 2.2.6.1), with the same name as the property.  The text value of the element MUST be equal to the value of the property.  The property value is formatted, as described in the EDM Primitive Type Formats for XML Element Values table in Common Serialization Rules for XML-based Formats (section 2.2.6.1).

2.2.6.5.4   Collection of EDMSimpleType Values

A collection of EDMSimpleType values MUST be represented as a single XML document with the root element of the document equal to the name of the Service Operation returning the values.  The root element and all its child elements MUST exist in the Data Service Metadata namespace, as described in Common Serialization Rules for XML-based Formats (section 2.2.6.1).

Each value in the collection must be represented as a child element of the root element and be named 'element'.  The text value of the XML element MUST be formatted, as described in the EDM Primitive Type Formats for XML Element Values table in Common Serialization Rules for XML-based Formats (section 2.2.6.1).

2.2.6.5.5   Links

Links represent unidirectional associations or one direction of a bidirectional association between EntityTypes.  Using the Customer and Order EntityTypes, associations and instance sample data, as described in Appendix A: Sample Entity Data Model and CSDL Document (section 6),  the set of Links from the Customer with EntityKey 'ALFKI' to Order instances are represented by a set of URIs, with each URI in the set identifying a single Order that is linked to from the Customer.  Such Link information MUST be serialized as an XML document that conforms to the XSD Schema [XMLSCHEMA1] shown in the following XSD Schema for a set of Links Represented using XML listing.  In the serialization, one URI element MUST exist for each link, with the text value of the element equal to the canonical URI of the linked-to EntityType instance.  Additionally, the target namespace MAY be server-specific, as described in Common Serialization Rules for XML-based Formats (section 2.2.6.1).

Listing: XSD Schema for a set of Links Represented using XML

A single Link, which is not part of a set, MUST be serialized as an XML document that conforms to the XSD Schema [XMLSCHEMA1] shown in following XSD Schema for a single Link Represented listing using XML.  The definition of the URI element in this case is unchanged from above.  The targetNamespace in the XSD MAY be server-specific, as described in Common Serialization Rules for XML-based Formats (section 2.2.6.1).

Listing: XSD Schema for a single Link Represented using XML

For example, using the sample model and instance data, as described in Appendix A: Sample Entity Data Model and CSDL Document (section 6), the links from the Customer with EntityKey entity 'ALFKI' to Order instances are represented as shown below.

Listing: Example of Links Formatted as XML

2.2.6.5.5.1   Inlinecount Representation (collections of Links)

This section defines an extended representation of a collection of links from that described in section 2.2.6.5.5. This representation of a collection of links is only supported in version 2.0 of the extensions defined by this specification to the AtomPub protocol.

A request URI MAY contain an $inlinecount System Query Option to indicate that the count of the number of links represented by the query should be included in the collection of links returned by a data service.

The count value included in the result MUST be enclosed in an <m:count> element which MUST be the first child element of the root <links> element.

2.2.7   Request Types

This document defines requests that a client can send to a data service.

The request types defined in this document either extend the request types defined in AtomPub, as specified in [RFC5023], by providing additional rules for each type. Or, they add additional types, in addition to those defined in [RFC5023].

In general, this document adopts the protocol semantics of AtomPub, as specified in [RFC5023], but extends AtomPub to allow the use of alternate formats (such as JSON [RFC4627]), in addition to Atom, and defines a URI addressing scheme for the abstract data model used in this document.  This document's data model maps 1-to-1 to the model constructs defined in AtomPub and defines additional constructs not present in the AtomPub model.

As specified in [RFC5023] and extended in this section, the requests from the client and the corresponding responses from the server are exchanged using HTTP request methods.  Each request type defined is mapped to an HTTP request method (for example, GET, POST, and so on) and HTTP request URI pair.

In general, the request types defined allow clients to:

§ Retrieve, edit, and delete Entity Data Model constructs represented as data service or AtomPub resources using HTTP's GET, PUT, and DELETE methods.  For further details see Retrieve Request Types (section 2.2.7.2), Update Request Types (section 2.2.7.3), and Delete Request Type (section 2.2.7.4).

§ Insert new EntityType instances into an EntitySet represented as an AtomPub Collection.  See Insert Request Types (section 2.2.7.1) for details.

§ Invoke a data service Service Operation.  For further details see Invoke Request (section 2.2.7.5).

§ Package many requests using a batch request type.  See Batch Request (section 2.2.7.6) for details.

§ Issue any of the above non-batch operations using a technique commonly referred to as POST tunneling (Tunneled Requests (section 2.2.7.7)).

This section defines the syntax rules for each request type.  Any ABNF syntax rules that are not specified in [RFC5234] or [RFC4627] use the extensions defined in [RFC2616].  The following are common ABNF syntax rules used throughout this section.

Listing: Common Grammar Rules for Request Types

2.2.7.1   Insert Request Types

This section defines all the insert request types a client may send to a data service.  All insert requests use the HTTP POST request method.  The type of insert action is further defined by the request URI used in a POST request.

Section 2.2.6.1.1 defines the InsertEntity request type which enables a client to insert a  new EntityType instance into an EntitySet.

Section 2.2.6.1.2 defines the InsertLink request type which is used to add a new link between EntityTypes instances.

2.2.7.1.1   InsertEntity Request

The purpose of the InsertEntity Request is to enable a new EntityType instance, potentially with new related entities, to be inserted into an EntitySet.  The base rules and semantics of this request type are defined by AtomPub, as specified in [RFC5023] section 5.3 - Creating a Resource, and, as described in Abstract Data Model (section 2.2.1), Entity Data Model constructs are mapped directly to data model concepts used in AtomPub.  For example, EntityTypes are AtomPub Entry Resources and collections of entities (Entity Sets, and so on) are AtomPub Collections.  This section adds constraints to those defined in AtomPub for this request type.

As specified in [RFC5023] section 9.2, insert requests use the HTTP POST method and the request URI must represent an AtomPub Collection.  Because a collection maps to a conceptual schema definition language (CSDL) in an Entity Data Model, the HTTP request line URI MUST be any valid data service URI , as defined in URI Format: Resource Addressing Rules (section 2.2.3